Skip to main content

Working with Changes

The core workflow in Atomic — track files, record changes, review diffs, and navigate history.

Commands​

CommandDescription
addAdd files to be tracked
removeRemove files from tracking (alias: rm)
moveMove or rename tracked files (alias: mv)
statusShow modified, added, deleted, and untracked files
diffShow differences between working copy and last recorded state
recordCreate a new change from tracked file modifications
reviseModify a previously recorded change in-place
logDisplay the history of changes on the current view
changeInspect details of a specific change by hash or sequence number
insertInsert changes from another view or change file
unrecordRemove the last change from the current view
restoreRestore the working copy to the last recorded state

The Record Workflow​

Atomic's workflow is similar to Git but uses different terminology:

GitAtomicDescription
git addatomic addTrack a file
git statusatomic statusSee what changed
git diffatomic diffReview differences
git commitatomic recordCreate a change
git commit --amendatomic reviseModify the last change
git logatomic logView history
git showatomic changeInspect a specific change

The key difference: Atomic records changes (patches), not snapshots. A change is a set of composable graph operations that can be applied, unapplied, and reordered.

Typical Workflow​

# 1. Track files
atomic add src/main.rs src/lib.rs

# 2. Make edits to your files

# 3. Review what changed
atomic status
atomic diff

# 4. Record the change
atomic record -m "Add authentication module"

# 5. View history
atomic log

Recording Changes​

The record command creates a new change from all tracked file modifications:

# Record with a message
atomic record -m "Fix null pointer in config parser"

# Record all changes (including newly created files)
atomic record --all -m "Initial project setup"

# Record with a specific diff algorithm
atomic record --algorithm patience -m "Refactor auth module"

Each recorded change includes:

  • Graph operations — The low-level vertex/edge modifications
  • Semantic layer — Line-level and token-level operations for display
  • Metadata — Author, timestamp, message, dependencies
  • Provenance — AI model and cost data (if recorded by an agent)

Revising Changes​

Unlike Git where --amend only works on HEAD, Atomic can revise any change in the view:

# Revise the most recent change
atomic revise -m "Better commit message"

# Revise only the message (no content changes)
atomic revise --reword -m "Fix typo in auth module"

# Revise a previous change
atomic revise @~1

Subsequent changes are automatically re-applied on top. See revise for details.

Reviewing Changes​

Status​

# See all changes
atomic status

# Short format
atomic status --short

Diff​

# Diff all tracked files
atomic diff

# Diff a specific file
atomic diff src/main.rs

# Show only statistics
atomic diff --stat

# Use patience diff algorithm
atomic diff --algorithm patience

History​

# View change log
atomic log

# View a specific change
atomic change ABC12345

# View the most recent change
atomic change

Inserting Changes​

The insert command moves changes between views or inserts change files:

# Insert a single change by hash
atomic insert ABC12345

# Insert changes from another view
atomic insert view feature --to-view main

# Cherry-pick specific changes
atomic insert change ABC123 DEF456 --to-view main

# Preview what would be inserted
atomic insert preview feature --to-view main

See Also​