EasyGit Backup
Version: 1.0
Platform: macOS 13 (Ventura) or later
Updated: September 2026
Support: cawingcrows.misic@gmail.com
HTML version for hosting: <code>../website/manual.html</code> · PDF: <code>USER_MANUAL.pdf</code>
1. What EasyGit Backup does
EasyGit Backup is a native macOS utility for developers who keep Git repositories in iCloud Drive and manage them with EasyGit.
iCloud can evict inactive files into dataless placeholders. Ordinary backup tools may archive empty stubs. EasyGit Backup:
1. Discovers your Git repositories (including nested Xcode layouts)
2. Detects and materializes iCloud dataless files when needed
3. Creates verified git bundle snapshots with SHA-256 checksums
4. Lets you schedule, verify, canary-test, and restore safely
All processing is local-first. There is no EasyGit Backup account, advertising SDK, or analytics backend.
2. System requirements
| Item | Requirement |
|---|---|
| macOS | 13.0 Ventura or newer |
| Git | Apple Git at `/usr/bin/git` (Xcode or Command Line Tools) |
| Disk | Enough free space for staging + destination snapshots |
| Optional | EasyGit installed for richest discovery; iCloud Drive for cloud-hosted repos |
| Network | Online when materializing dataless iCloud files |
3. First-launch checklist
1. Open EasyGit Backup and wait for the Dashboard refresh.
2. Open Settings & Destinations and confirm a Primary destination (default local storage under ~/.easygit-backup/storage/ is fine).
3. Optionally add a secondary destination (external disk, NAS mount, or another sync folder).
4. Click Backup All Repositories once.
5. Open Backup History → Verify Integrity on the new snapshot.
6. Optionally run Canary Test Restore.
7. Open Scheduler, choose Daily / Hourly / Weekly, set a time, then click Save & Activate Schedule.
8. Confirm the sidebar / Scheduler shows Daemon Active and Dashboard shows a sensible Next Backup.
4. Dashboard
The Dashboard is your health overview:
- Git Repositories — count of discovered projects
- iCloud Dataless — files still only in the cloud (needs download before a complete working-tree capture)
- Total Snapshots — backups on the primary destination
- Backup Storage Free — free space on the primary destination
- Schedule / next-run status and destination summary
- Sample repositories and recent snapshots
- Primary action: Backup All Repositories
Use the toolbar Refresh control after adding projects or changing destinations.
5. Repositories
Browse every discovered Git repository.
For each repo you can:
- See branch, latest commit, path, and dataless warnings
- Backup that repository alone (including working-tree extras when enabled)
- Restore from the latest matching snapshot to a staging folder
- Reveal in Finder
Use the search field to filter large inventories.
How discovery works
EasyGit Backup scans configured discovery paths (often your Xcode / iCloud Drive projects folder) and looks for .git at the folder root and one level of nesting (typical Xcode Project/Project/.git layouts). When available, it also consults EasyGit’s local metadata to recognize managed repositories.
6. Backup History
Each snapshot card shows ID, timestamp, size, success state, and included repository names.
Actions:
| Action | What it does |
|---|---|
| **Verify Integrity** | Re-checks SHA-256 checksums and runs `git bundle verify` |
| **Canary Test Restore** | Restores one repository into a temporary scratch folder and runs `git fsck` |
| **Restore to Staging** | Restores repositories under `~/.easygit-backup/restores/<snapshot_id>/` |
Staging restores are non-destructive by default. Prefer them over in-place overwrite unless you intentionally need to replace a working copy.
7. Scheduler
Background backups use a macOS LaunchAgent labeled me.easygit.backup.
Cadence options
- Daily — runs at the chosen hour:minute
- Hourly — runs every hour at the chosen minute
- Weekly — runs on the configured weekday and time
- Manual — no calendar timer (on-demand only)
Next-run behavior
- If today’s scheduled clock time is still ahead, next run is today.
- If that time already passed, next run rolls to the next day (or next matching weekday for weekly).
Activating the daemon
1. Choose cadence and time.
2. Optionally enable Trigger on System Wake / Login.
3. Click Save & Activate Schedule.
4. Confirm Daemon Active.
The GUI does not need to stay open for scheduled runs. Scheduled execution launches the app (or CLI helper) with an automatic backup flag, performs the job, then exits.
Uninstalling the daemon
Use Uninstall Daemon in Scheduler, or remove ~/Library/LaunchAgents/me.easygit.backup.plist after unloading the agent.
8. Settings & Destinations
Destinations
- One destination should be marked Primary
- Local folders, external disks, and mounted NAS / secondary cloud folders are supported
- Optional AES-256-GCM encryption for off-machine destinations (Keychain-backed secrets)
Do not claim live S3 upload unless your build has a fully implemented S3 backend.
Retention
- Keep last *N* full backups
- Keep incremental / non-full snapshots for *D* days
- Keep at least one weekly snapshot for *M* months
Notifications & options
- Include working-tree changes by default
- Notify on failure / success (local macOS notifications)
9. What gets backed up
| Scope | Contents |
|---|---|
| Full / single repo | Git history via `git bundle` (branches, tags, HEAD as configured) |
| Working-tree extras (optional) | Uncommitted diffs / untracked capture when enabled |
| EasyGit metadata (when included) | Local EasyGit preferences / metadata copies used for discovery |
Empty repositories (no commits yet) are recorded but do not create a bundle.
10. Restore & verification best practices
1. Always Verify Integrity after the first backup to a new destination.
2. Run a Canary Test Restore before trusting encryption settings or a new disk.
3. Restore to staging, inspect with Finder / Xcode / git log, then copy into place intentionally.
4. Prefer keeping at least one off-machine destination for disaster recovery.
11. Important paths
| Path | Purpose |
|---|---|
| `~/.easygit-backup/config.json` | App configuration |
| `~/.easygit-backup/storage/` | Default local snapshot storage |
| `~/.easygit-backup/logs/` | Execution logs and per-snapshot manifests |
| `~/.easygit-backup/restores/` | Staging restore output |
| `~/Library/LaunchAgents/me.easygit.backup.plist` | Background schedule agent |
12. CLI companion (optional)
If you install the easygit-backup CLI (Swift Package Manager release binary), you can automate from Terminal:
easygit-backup status
easygit-backup inventory
easygit-backup backup full
easygit-backup backup repo "MyProject" --working-tree
easygit-backup history
easygit-backup verify <snapshot_id>
easygit-backup restore repo "MyProject" --snapshot <snapshot_id>
easygit-backup schedule status
easygit-backup schedule install daily
The Mac app can also perform scheduled backups without a separately installed CLI when the LaunchAgent points at the app binary.
13. Troubleshooting
| Symptom | What to try |
|---|---|
| No repositories found | Confirm discovery paths; ensure `.git` exists; wait for iCloud folder structure to sync |
| High dataless count | Stay online; re-run backup after downloads finish |
| Daemon Inactive | Save & Activate Schedule; check LaunchAgents folder permissions |
| Missed schedule | Enable wake/login catch-up; keep Mac awake or allow wake; inspect `~/.easygit-backup/logs/` |
| Destination unhealthy | Remount disk / reconnect NAS; use Test destinations if available |
| Restore blocked | Use staging; avoid overwriting dirty working trees without explicit force |
14. Privacy & security
- No advertising or third-party analytics SDKs
- No EasyGit Backup cloud account
- Backups stay on destinations you configure
- Optional destination encryption uses AES-256-GCM with secrets in the macOS Keychain
- Support contact: cawingcrows.misic@gmail.com
- Privacy Policy: https://cawingcrows.github.io/EasyGit-Backup/privacy.html
15. Getting help
Email cawingcrows.misic@gmail.com with:
- macOS version and EasyGit Backup version
- What you expected vs what happened
- Whether Daemon shows Active
- Relevant lines from `~/.easygit-backup/logs/`
- Destination type (local / NAS / secondary folder)
We typically respond within 1–2 business days.
Need more help? Visit Support or email cawingcrows.misic@gmail.com.