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

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 from-view feature --to-view main

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

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

See Also​