archive.md
markdown
| 1 | # `muse archive` — export a snapshot as a portable archive |
| 2 | |
| 3 | `muse archive` packages any historical snapshot into a self-contained `tar.gz` or `zip` file. The archive contains only the tracked files — no `.muse/` metadata is included. This makes it the canonical format for distributing a specific version of your work. |
| 4 | |
| 5 | ## Usage |
| 6 | |
| 7 | ```bash |
| 8 | muse archive # HEAD snapshot → <sha12>.tar.gz |
| 9 | muse archive --ref v1.0.0 # tag tip → <sha12>.tar.gz |
| 10 | muse archive --ref feat/audio # branch tip |
| 11 | muse archive --ref a1b2c3d4 # specific commit SHA prefix |
| 12 | muse archive --format zip --output out.zip # zip format, custom name |
| 13 | muse archive --prefix myproject/ # add directory prefix inside archive |
| 14 | ``` |
| 15 | |
| 16 | ## Options |
| 17 | |
| 18 | | Flag | Default | Description | |
| 19 | |------|---------|-------------| |
| 20 | | `--ref`, `-r` | HEAD | Branch name, tag, or commit SHA to archive | |
| 21 | | `--format`, `-f` | `tar.gz` | Archive format: `tar.gz` or `zip` | |
| 22 | | `--output`, `-o` | `<sha12>.<format>` | Output file path | |
| 23 | | `--prefix` | (none) | Directory prefix prepended to all paths inside the archive | |
| 24 | |
| 25 | ## Supported formats |
| 26 | |
| 27 | | Format | Extension | Notes | |
| 28 | |--------|-----------|-------| |
| 29 | | `tar.gz` | `.tar.gz` | Compressed tar, widely supported | |
| 30 | | `zip` | `.zip` | ZIP with DEFLATE compression, Windows-friendly | |
| 31 | |
| 32 | ## Output |
| 33 | |
| 34 | ``` |
| 35 | ✅ Archive: release-v1.0.tar.gz (47 file(s), 312.8 KiB) |
| 36 | Commit: a1b2c3d4ef56 feat: release v1.0 |
| 37 | ``` |
| 38 | |
| 39 | ## What is included |
| 40 | |
| 41 | - All files tracked in the snapshot manifest at the specified ref. |
| 42 | - Files are stored under their original relative paths (or under `--prefix/` if specified). |
| 43 | |
| 44 | ## What is NOT included |
| 45 | |
| 46 | - `.muse/` metadata (commits, snapshots, object store) |
| 47 | - Untracked files from `state/` |
| 48 | - Reflog entries, branch refs, config |
| 49 | |
| 50 | ## `--prefix` usage |
| 51 | |
| 52 | The prefix flag lets you distribute archives that unpack into a named directory, matching the convention of most open-source releases: |
| 53 | |
| 54 | ```bash |
| 55 | muse archive --prefix myproject-1.0/ --output myproject-1.0.tar.gz |
| 56 | # Inside the archive: myproject-1.0/README.md, myproject-1.0/src/main.py, … |
| 57 | ``` |
| 58 | |
| 59 | ## Agent workflows |
| 60 | |
| 61 | ### Create a release artifact |
| 62 | |
| 63 | ```bash |
| 64 | muse tag v1.0.0 --message "Release 1.0" |
| 65 | muse archive --ref v1.0.0 --format zip --output release-v1.0.zip |
| 66 | ``` |
| 67 | |
| 68 | ### Batch-archive all tags |
| 69 | |
| 70 | ```bash |
| 71 | for tag in $(muse tag list --names-only); do |
| 72 | muse archive --ref "$tag" --output "archives/$tag.tar.gz" |
| 73 | done |
| 74 | ``` |
| 75 | |
| 76 | ### Distribute a specific commit |
| 77 | |
| 78 | ```bash |
| 79 | # Share an exact commit without exposing history: |
| 80 | muse archive --ref a1b2c3d4 --prefix shared-experiment/ --output experiment.zip |
| 81 | ``` |
| 82 | |
| 83 | ## Exit codes |
| 84 | |
| 85 | | Code | Meaning | |
| 86 | |------|---------| |
| 87 | | 0 | Success | |
| 88 | | 1 | Ref not found, unknown format, or snapshot missing | |