Breadway/bread
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: document sync export/import and updated snapshot layout

Browse source
This commit is contained in:
Breadway 2026-05-16 22:17:26 +08:00
parent fc27916a5d
commit 3be8eec065
2 changed files with 83 additions and 32 deletions
Download patch file Download diff file Expand all files Collapse all files

65
Documentation.md
View file

@ -138,16 +138,18 @@ installed_at = "2026-01-01T00:00:00Z"
## Sync: snapshot and restore ## Sync: snapshot and restore
Bread sync snapshots your Bread config, arbitrary dotfiles, and installed package lists into a Git repository. Pull it on another machine to restore state. Bread sync snapshots your config, dotfiles, and installed packages into a local Git repository. Use `export`/`import` to move state between machines — no git remote required.
```bash ```bash
# First-time setup # First-time setup (remote optional)
bread sync init
bread sync init --remote git@github.com:you/bread-config.git bread sync init --remote git@github.com:you/bread-config.git
# Snapshot and push # Commit local snapshot
bread sync push bread sync push
bread sync push --message "before reinstall"
# On another machine: pull and apply # Apply snapshot to this machine
bread sync pull bread sync pull
# Also reinstall packages from snapshot # Also reinstall packages from snapshot
@ -156,12 +158,55 @@ bread sync pull --install-packages
# See what has changed # See what has changed
bread sync status bread sync status
bread sync diff bread sync diff
bread sync diff --remote
# List known machines # List known machines
bread sync machines bread sync machines
``` ```
### Portable export/import
`export` creates a self-contained snapshot directory or `.tar.gz` — no git auth needed.
```bash
# Create a portable snapshot (defaults to ./bread-export-<machine>-<date>.tar.gz)
bread sync export
# Export to a specific path
bread sync export --output ~/backups/bread.tar.gz
bread sync export --output /mnt/usb/bread-snapshot/ # directory
# Apply a snapshot on another machine
bread sync import bread-export-hermes-2026-05-16.tar.gz
bread sync import /mnt/usb/bread-snapshot/
# Also install packages from the snapshot
bread sync import bread-export.tar.gz --install-packages
# Skip cloning git repos back to their original locations
bread sync import bread-export.tar.gz --no-clone-repos
# Skip confirmation prompt
bread sync import bread-export.tar.gz --yes
```
Each export snapshot includes:
| Directory | Contents |
|-----------|----------|
| `bread/` | `~/.config/bread/` (your Bread config) |
| `configs/` | Common app configs (hypr, nvim, kitty, waybar, fish, etc.) |
| `dotfiles/` | Individual files: `.gitconfig`, `.zshrc`, `.zprofile`, `.zshenv`, SSH config, etc. |
| `local-bin/` | `~/.local/bin/` scripts (non-symlink, <512 KB) |
| `local-fonts/` | `~/.local/share/fonts/` |
| `systemd/` | `~/.config/systemd/user/` units |
| `system/` | System files: udev rules, modprobe, sysctl, NetworkManager, bluetooth (root-only paths skipped unless run with sudo) |
| `packages/` | Package lists (pacman.txt, pip.txt, cargo.txt, npm.txt) |
| `machines/` | Per-machine profile with tags and last-sync time |
| `manifest.toml` | Path map for exact restoration on import |
| `restore.sh` | Shell script for manual restore (system files shown as sudo commands) |
**Git repository tracking:** at export time, all git repositories with remotes found under `~`, `~/Projects`, `~/Documents`, and `~/.config` are auto-committed and pushed. Their remote URLs and branches are recorded in the manifest. On import, `--no-clone-repos` suppresses cloning them back.
Configure sync in `~/.config/bread/sync.toml`: Configure sync in `~/.config/bread/sync.toml`:
```toml ```toml
@ -182,16 +227,6 @@ include = ["~/.config/nvim", "~/.config/waybar"]
exclude = ["**/.git", "**/*.cache"] exclude = ["**/.git", "**/*.cache"]
``` ```
The sync repo stores:
```
~/.local/share/bread/sync-repo/
├── bread/ ← ~/.config/bread/ snapshot
├── configs/ ← delegate paths (nvim, waybar, etc.)
├── machines/ ← per-machine profiles with tags and last-sync time
└── packages/ ← package snapshots (pacman.txt, pip.txt, etc.)
```
## Debugging tips ## Debugging tips
- Run `bread events` to see live normalized events. - Run `bread events` to see live normalized events.

50
README.md
View file

@ -201,14 +201,19 @@ bread modules update [name] # Re-install one or all GitHub-sourced mod
bread modules info <name> # Show full manifest and daemon status bread modules info <name> # Show full manifest and daemon status
# Sync # Sync
bread sync init # Initialize sync for this machine bread sync init # Initialize sync for this machine (remote optional)
bread sync push # Snapshot and push current state to remote bread sync push # Commit local snapshot
bread sync pull # Pull and apply latest state from remote bread sync push --message "note" # Commit with a custom message
bread sync pull # Apply local snapshot to this machine
bread sync pull --install-packages # Also install packages from snapshot bread sync pull --install-packages # Also install packages from snapshot
bread sync status # Show what has changed since last push bread sync status # Show what has changed since last push
bread sync diff # Show file-level diff vs last commit bread sync diff # Show file-level diff vs last commit
bread sync diff --remote # Show diff vs remote
bread sync machines # List known machines from sync repo bread sync machines # List known machines from sync repo
bread sync export # Create a portable .tar.gz snapshot (no git auth)
bread sync export --output path # Export to a specific file or directory
bread sync import <path> # Apply a portable snapshot (.tar.gz or directory)
bread sync import <path> --install-packages # Also install packages
bread sync import <path> --no-clone-repos # Skip cloning git repos
``` ```
--- ---
@ -266,27 +271,31 @@ return M
## Sync system ## Sync system
Bread sync snapshots your entire setup — Bread config, arbitrary dotfiles, and package lists — and stores it in a Git repository. Pull it on another machine to restore. Bread sync snapshots your entire setup — Bread config, dotfiles, fonts, systemd units, package lists, and git repos — into a local Git repository. Use `export`/`import` to move state between machines without needing a git remote.
```bash ```bash
# First-time setup # First-time setup (remote is optional)
bread sync init
bread sync init --remote git@github.com:you/bread-config.git bread sync init --remote git@github.com:you/bread-config.git
# Push current state # Commit a local snapshot
bread sync push bread sync push
# On another machine: pull and apply # Create a portable .tar.gz (no git auth required)
bread sync pull bread sync export
# Check what's pending # On another machine: apply the snapshot
bread sync status bread sync import bread-export-hermes-2026-05-16.tar.gz
# Also install packages on import
bread sync import bread-export.tar.gz --install-packages
``` ```
Configure what gets synced in `~/.config/bread/sync.toml`: Configure what gets synced in `~/.config/bread/sync.toml`:
```toml ```toml
[remote] [remote]
url = "git@github.com:you/bread-config.git" url = "git@github.com:you/bread-config.git" # optional
branch = "main" branch = "main"
[machine] [machine]
@ -302,14 +311,21 @@ include = ["~/.config/nvim", "~/.config/waybar"]
exclude = ["**/.git", "**/*.cache"] exclude = ["**/.git", "**/*.cache"]
``` ```
The sync repo stores: A portable export snapshot contains:
``` ```
sync-repo/ bread-export-hermes-2026-05-16/
├── bread/ ← ~/.config/bread/ snapshot ├── bread/ ← ~/.config/bread/
├── configs/ ← delegate paths (nvim, waybar, etc.) ├── configs/ ← hypr, nvim, kitty, waybar, fish, dunst, btop, …
├── dotfiles/ ← .gitconfig, .zshrc, .zprofile, .zshenv, ssh config, …
├── local-bin/ ← ~/.local/bin/ scripts
├── local-fonts/ ← ~/.local/share/fonts/
├── systemd/ ← ~/.config/systemd/user/ units
├── system/ ← udev rules, modprobe, sysctl (sudo required for some)
├── packages/ ← pacman.txt, pip.txt, cargo.txt, npm.txt
├── machines/ ← per-machine profiles ├── machines/ ← per-machine profiles
└── packages/ ← package snapshots (pacman.txt, pip.txt, etc.) ├── manifest.toml ← path map for exact restore
└── restore.sh ← shell script for manual restore
``` ```
--- ---