Source Code Management

Description

jj workflow for preserving all work. Nothing is ever lost.

Core Principle

Every change is automatically tracked. Nothing is ever lost.

In jj, the working copy (@) is always a commit. There's no staging area. Every file save is immediately part of the current commit. This makes "losing work" nearly impossible.

Rules

1. Commit After Every Testable Change

After each TDD cycle (Red → Green → Verify), finalize and start fresh:

jj commit -m "descriptive message"

This creates a new empty working copy. Don't batch commits. Don't wait for "a good stopping point." The worktree will be squash-merged anyway - frequent commits only help you.

2. jj Auto-Tracks Everything

Unlike git, jj has no "uncommitted code at risk" - your working copy IS a commit being edited. However, before operations that modify history:

• Before running jj restore (discards working copy changes)
• Before running jj abandon (removes commits)
• Before closing the session (commit to finalize)

Finalize with jj commit or jj describe first.

3. Experiments: Commit, Try, Backout

When experimenting:

# 1. Commit the experiment
jj commit -m "experiment: trying X approach"

# 2. Test/evaluate the experiment

# 3a. If keeping: continue working
# 3b. If discarding: backout cleanly
jj backout -r @-

The experiment is preserved in history even after backing out. You can always recover it.

4. Unknown Changes: Describe First, Understand Later

If you encounter changes you don't understand:

# Wrong: discard unknown changes
jj restore  # DANGEROUS - loses working copy changes

# Right: preserve then investigate
jj commit -m "checkpoint: unknown changes"
jj diff -r @-  # examine what changed
# Later: backout if unwanted

5. Discarding Code: Commit, Then Delete

Even when intentionally removing code:

# 1. Commit current state
jj commit -m "checkpoint before removing X"

# 2. Delete the code
# 3. Commit the deletion
jj commit -m "remove X"

Now you can recover the deleted code from history if needed.

Why This Matters

• Recovery: Any past state is one jj edit away
• Debugging: Use jj log and manual bisection to find issues
• Confidence: Experiment freely knowing nothing is lost
• Squash merge: All these commits collapse to one clean commit at release

Key Commands

Anti-patterns