Every commit in Arche is in one of three phases: draft, public, or secret. The phase determines what operations are freely allowed and how the commit behaves during sync.
Draft commits are your in-progress work. They can be freely amended, rebased, split, folded, or squashed without passing any additional flags. They represent a part of history that you own and haven't published.
Public commits are shared. They arrived via a pull, or they were pushed to a remote. Rewriting a public commit requires --force-rewrite, which is a signal that you understand you are changing history that others may have already based work on. On a normal team workflow you would coordinate before doing this.
Secret commits are hidden from sync. They are freely rewritable like drafts, but they are never included in push or pull operations. They are useful for experiments, local notes, or work that should never leave your machine.
Phase transitions happen automatically at sync time. When you push a draft bookmark, Arche promotes the reachable draft commits to public within the same transaction as the push. When you pull, incoming commits arrive as public. The promotion happens atomically; there is no window where a commit is public in memory but still draft on disk.
Manual phase changes are possible:
arche phase set ch:kptxoyvr draft
arche phase set ch:kptxoyvr secret
Demoting a public commit to draft on your own machine is allowed and non-destructive. It just changes your local phase record. The remote still considers it public, so you will need to coordinate with collaborators if you intend to rewrite it.
arche clone https://arche.example.com/myrepo
This fetches all objects from the remote into a new local store, materialises the working copy from the remote's HEAD, and saves the remote URL as origin in the local config. The clone is a full copy, not a shallow one. All history is local; subsequent operations that don't involve syncing work entirely offline.
SSH is also supported:
arche clone arche+ssh://arche.example.com/myrepo
Authentication over SSH uses your SSH key pair. Over HTTPS, a bearer token is used:
arche clone https://arche.example.com/myrepo --token <your-api-token>
The token is stored in the local config after the first use with --token so you don't need to repeat it.
arche sync
Without flags, this pushes your bookmarks and pulls from the remote in a single operation. The push and pull are not independent rounds; Arche uses a Bloom filter negotiation protocol to determine which objects the remote needs and which ones you need, then transfers packed objects in both directions. Up to three follow-up rounds handle Bloom false positives by requesting exact hashes.
To pull only:
arche sync --pull
To push only:
arche sync --push
All received commit objects are written to store.db in a single transaction. Issues and wiki pages are transferred alongside and written to issues.db. If the sync is interrupted, nothing is partially applied.
Pushing a bookmark that points to a public commit requires --force-public, since rewriting public history on the remote is a significant operation that should be intentional. For draft bookmarks, a normal push is sufficient even if it rewrites the remote bookmark.
The stack workflow is the recommended way to submit multiple related changes for review. To see what's in your current draft stack:
arche stack list
After creating a chain of draft commits, publish the stack for review:
arche stack push
This walks the draft chain from HEAD back to the nearest public or secret ancestor, creates a stack/<change-id-prefix> bookmark for each commit, and pushes all of them in one operation. The forge groups these bookmarks visually into a stack, showing per-change diffs, authorship, and review status, linked by change ID.
When a review returns line-level edits scattered across the stack, make the changes in the working copy and run:
arche absorb
This blame-walks the draft commit chain to find which ancestor last introduced the context around each changed hunk, then folds the hunk into that commit. Hunks that can't be attributed to any draft ancestor are left in the working copy unchanged. After absorb, run arche stack push again to publish the updated versions.
When a change has been reviewed and is ready to ship, promote it to public:
arche stack land [change-id]
Without a change ID, this lands the oldest (bottom-most) draft in the stack. Pass --bookmark <name> to advance or create a named bookmark to the landed commit, which makes it visible as a branch tip on the forge and to other clones.
If the draft chain becomes mis-parented after a manual edit or import, re-chain it with:
arche stack rebase
When you amend a change at the bottom of the stack, arche snap --amend automatically rebases the commits above it. Running arche stack push again pushes the updated bookmarks. Because review state is keyed by change ID (which never changes across rewrites), the reviewer can see what was updated between versions.
The remote URL and authentication settings live in .arche/config.toml. After cloning, the file will contain something like:
[[remote]]
name = "origin"
url = "https://arche.example.com/myrepo"
token = "your-api-token"
Multiple named remotes are supported by adding more [[remote]] entries. Pass the remote name to arche sync explicitly when working with more than one:
arche sync upstream
If a project uses both Arche and Git (for CI systems or contributors who haven't migrated), enable the Git mirror in the config:
[git]
enabled = true
remote = "origin"
With this setting, arche snap also writes a Git commit to .git/, and arche sync runs a corresponding git push or git pull to the configured Git remote. The Arche and Git histories are kept in sync transparently. This is a deliberate tradeoff: Git compatibility comes with some write overhead, but it lets a team adopt Arche incrementally without abandoning their existing infrastructure.
arche bundle archive.tar.gz
Creates a complete archive containing store.db, issues.db, config.toml, and all pack files. Useful for backups or for transferring a repository without a network connection. The bundle can be extracted and used directly as a repository.