arche / wiki / Workflow Examples

Workflow Examples

This page is not a command reference. It is a set of concrete ways to work with Arche, ordered from the simplest loop to the kinds of history surgery and collaboration patterns that only show up once a repository is under steady use.

If you are new to the system, read the first two sections and stop there. The later sections build on the same ideas: the working copy is always a draft commit, change IDs survive rewrites, and bookmarks are publication pointers rather than the unit of day to day editing.

1. The Simplest Possible Workflow

This is the default loop when you are working alone on a small change.

1. Edit files.
2. Check what changed.
3. Snapshot the result.
4. Repeat until the change is done.

Typical commands:

arche status
arche diff
arche snap "Add config parser"

You do not stage files first. You do not create a branch first. You just modify the working copy and snapshot when the state is coherent.

If the change is not ready in one shot, keep taking snapshots as you make progress:

arche snap "Parse bare key value pairs"
arche snap "Handle quoted values and escapes"
arche snap "Report invalid syntax cleanly"

That gives you a small local chain of draft commits. Nothing is public yet.

2. A Straight Line to main

This is the right workflow when the work is ready and you want main to advance to your current tip.

1. Finish the local draft chain.
2. Move main to the current HEAD.
3. Push main.

arche bookmark set main
arche sync --push

The bookmark points only at the top commit, but that is enough. All ancestor commits reachable from that tip are included automatically.

This is the simplest publication model in Arche. You do not need arche stack push here. stack push is for review bookmarks such as stack/<change-id-prefix>. If the work is already ready to become main, moving main itself is the direct path.

A good mental model is:

• arche snap creates or refines local draft history.
• arche bookmark set main chooses what line of history should be published.
• arche sync --push makes the remote agree.

3. A Small Feature With One Cleanup Pass

A very common pattern is to develop quickly first, then clean up once the idea works.

Example:

arche snap "Get parser working"
arche snap "Wire parser into config loader"
arche snap "Add tests for invalid input"

Now review the history. If the first commit needs more work, check it out, amend it, and let Arche rebase the descendants automatically:

arche co ch:abcd1234
# edit files
arche snap --amend

Because change IDs survive rewrites, the identity of the amended change stays stable even though the content hash changes.

If the stack still looks good, publish it by moving main to the current tip:

arche co @
arche bookmark set main
arche sync --push

4. A Review Stack

Use a review stack when each commit should be discussed separately, or when you expect comments on individual steps rather than on the final combined result.

A typical sequence is:

arche snap "Add parser core"
arche snap "Add parser tests"
arche snap "Wire parser into CLI"

Before publishing for review, check the stack:

arche stack list

If the chain looks right, publish review bookmarks:

arche stack push

This creates stack/<change-id-prefix> bookmarks on the remote. The forge can then show each change as its own review unit while still understanding that they belong to one stack.

Use this when the stack is under review. Do not use it as a substitute for moving main when the stack is already approved and ready to land.

5. Review Feedback Across Several Commits

This is where arche absorb becomes useful.

Suppose a reviewer asks for three changes:

• rename one helper introduced in the bottom commit
• tighten validation in the middle commit
• fix an error message in the top commit

You can make all three edits directly in the working copy, without manually checking out each ancestor one by one. Then run:

arche absorb

Arche blame walks the draft chain, finds which ancestor last introduced the surrounding lines, and folds each hunk into the right draft commit.

The normal loop is:

arche stack list
arche absorb
arche stack push

Any hunk Arche cannot confidently attribute is left in the working copy unchanged. That is a safety property, not a failure. You can snapshot the remainder manually.

6. An Interrupted Task

Sometimes you are halfway through one change when a different task arrives.

If the partial work is not ready for a snapshot, shelf it:

arche shelve spike-notes

This stores the working copy state in store.db and restores the working directory to HEAD.

Handle the urgent task as normal:

# edit files
arche snap "Fix token expiry check"
arche bookmark set main
arche sync --push

Then restore the shelved work:

arche unshelve spike-notes

Use shelving when the work is real but not ready to become part of history yet. If the work is already coherent, a normal snapshot is usually better than a shelf.

7. A Conflict Heavy Rebase

Suppose your local draft stack is based on an older main, and the remote main has moved substantially.

The update flow is:

arche sync --pull
arche rebase main

If some commits no longer apply cleanly, Arche stores conflict objects in the replayed commits and continues rebasing the rest of the chain. At the end, the working copy reflects the rebased tip and any unresolved paths are materialised with conflict markers.

Resolve them one by one:

arche status
# edit conflicting files
arche resolve path/to/file
arche resolve other/file
arche snap "Resolve rebase conflicts"

If this was a review stack, publish the updated review bookmarks again:

arche stack push

If the whole stack is ready for main, move main and push instead:

arche bookmark set main
arche sync --push

8. Landing A Reviewed Stack

There are two common ways to finish a reviewed stack.

Option A: publish the whole line as main

If the entire stack is approved and should become the new trunk, move main to the tip:

arche bookmark set main
arche sync --push

This is the simplest outcome.

Option B: mark changes public one by one

If you want to mark a reviewed change as landed before the whole stack is published as main, use stack land:

arche stack land

That lands the oldest draft in the stack. To land a specific one:

arche stack land ch:abcd1234

And if you want a bookmark advanced at the same time:

arche stack land ch:abcd1234 --bookmark release

This is useful when review state matters independently from the final trunk bookmark, or when a stack is being landed gradually.

9. Backporting A Fix Without Rewriting Mainline History

Suppose a fix already exists on main, but you also need it on a release line.

Check out the release line and graft the fix:

arche co release-1.2
arche graft ch:fixabcd

graft copies the change onto the current HEAD, preserving its change ID and recording the relationship with an obsolescence marker. The original mainline history is untouched.

After checking the result, publish the release bookmark:

arche bookmark set release-1.2
arche sync --push

Use graft when the right answer is "apply this change here too", not "move the original commit".

10. A Hyper Complex Stack Maintenance Session

This is the kind of session that only shows up in a busy repository, but it demonstrates how the pieces fit together.

Imagine this situation:

• you have eight draft commits locally
• three are already under review via stack/... bookmarks
• one urgent production fix interrupts the work
• upstream main moved while review was happening
• the reviewer wants changes folded into earlier commits, not stacked as follow ups
• one commit also needs to be backported to a release line

A reasonable session looks like this:

arche shelve big-refactor
arche co main
# implement urgent fix
arche snap "Fix session renewal bug"
arche bookmark set main
arche sync --push
arche unshelve big-refactor
arche sync --pull
arche rebase main
arche status
# resolve conflicts
arche resolve path/one
arche resolve path/two
arche snap "Resolve rebase conflicts"
arche absorb
arche stack push
arche co release-1.2
arche graft ch:fixabcd
arche bookmark set release-1.2
arche sync --push

That is a lot of movement, but each step is still local and explicit. Nothing depends on hidden staging state or implicit branch switching.

The important thing is to keep the decisions separate:

• shelf only when the current working copy is not yet a good commit
• rebase when the base changed
• absorb when review feedback belongs inside earlier commits
• stack push when the result is still under review
• move main when the result is ready to be the new public tip
• graft when the same logical fix needs to exist on another line of history

Choosing The Right Publication Command

A lot of confusion disappears if you decide one thing first: are you publishing for review, or publishing as the new branch tip?

Use arche stack push when:

• each draft commit should appear as a separate review unit
• you want forge stack views and per change discussion
• the stack is still mutable

Use arche bookmark set main plus arche sync --push when:

• the work is ready
• main should advance to your current tip
• you do not need temporary review bookmarks

Use arche stack land when:

• a specific reviewed change should be marked public
• you want to land a stack incrementally
• publication phase matters separately from moving main

Once you make that decision, the rest of the workflow is usually obvious.