Skip to main content

atomic diff

Show differences between the working copy and recorded state.

Synopsis​

atomic diff [OPTIONS] [PATHS]...

Description​

The diff command displays the differences between your working copy (the files you're editing) and the pristine state (the last recorded state in the stack). This helps you review changes before recording them.

Unlike traditional VCS diff commands, Atomic computes differences based on the patch theory, showing semantic operations rather than just line-level changes. This enables:

  • Preview of what will be recorded
  • Identification of file additions, deletions, and modifications
  • Line-by-line change inspection
  • Selective change review

Options​

--repository <PATH>​

Specify the repository path if not running from within the repository directory.

atomic diff --repository /path/to/repo

--stack <STACK>​

Show differences relative to a specific stack instead of the current stack.

atomic diff --stack feature-branch

--json​

Output differences in JSON format for programmatic consumption.

atomic diff --json

--color <WHEN>​

Control colored output. Options: auto, always, never.

atomic diff --color always
atomic diff --color never

--unified <LINES>​

Number of context lines to show around changes. Default is 3.

# Show 5 lines of context
atomic diff --unified 5

# Show minimal context
atomic diff --unified 1

--patience​

Use the Patience diff algorithm instead of the default Myers algorithm. Can produce better diffs for certain types of changes.

atomic diff --patience

[PATHS]...​

Optional paths to limit diff output. Only show differences in specified files or directories.

# Diff specific file
atomic diff src/main.rs

# Diff directory
atomic diff src/

# Diff multiple paths
atomic diff src/ tests/ Cargo.toml

Examples​

Basic Usage​

# Show all changes in working copy
atomic diff

# Show changes in specific file
atomic diff README.md

# Show changes in directory
atomic diff src/

Controlling Output​

# More context lines
atomic diff --unified 10

# No color output (for piping)
atomic diff --color never

# JSON output for parsing
atomic diff --json

Using Different Algorithms​

# Default Myers algorithm
atomic diff

# Patience algorithm (better for refactoring)
atomic diff --patience

Review Before Recording​

# Make changes
echo "New content" >> file.txt

# Review changes
atomic diff

# Record if satisfied
atomic record -m "Update file"

Output Format​

Standard Diff Format​

diff --git a/src/main.rs b/src/main.rs
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,7 +1,8 @@
 fn main() {
-    println!("Hello, world!");
+    println!("Hello, Atomic!");
+    println!("Welcome to version control");
 }
 
 fn helper() {
     // Helper function
 }

File Status Indicators​

M  src/main.rs          # Modified
A  src/new_file.rs      # Added
D  src/old_file.rs      # Deleted
R  src/renamed.rs       # Renamed

Diff Sections​

  • Lines starting with -: Removed from the file (shown in red)
  • Lines starting with +: Added to the file (shown in green)
  • Lines with no prefix: Context lines (unchanged)
  • @@ -start,count +start,count @@: Hunk headers showing line ranges

Diff Algorithms​

Myers Algorithm (Default)​

The default Myers algorithm is fast and produces good results for most changes:

atomic diff

Best for:

  • Regular code changes
  • Small to medium edits
  • General purpose diffing

Patience Algorithm​

The Patience algorithm produces more intuitive diffs for refactoring and code movement:

atomic diff --patience

Best for:

  • Large refactoring
  • Code reorganization
  • Function/block movement
  • Complex changes

Example difference:

With Myers, function reordering might show as many small changes. With Patience, it clearly shows the functions were moved as blocks.

Binary Files​

Binary files are detected automatically and shown without content diff:

diff --git a/assets/logo.png b/assets/logo.png
Binary files differ

Empty Changes​

If there are no changes in the working copy:

$ atomic diff
# (no output)

Check exit code:

atomic diff
echo $?
# 0 = no changes
# 1 = changes present

Filtering by Path​

Limit diff output to specific paths:

# Single file
atomic diff src/main.rs

# Directory
atomic diff src/

# Multiple paths
atomic diff src/ tests/

# Specific files
atomic diff Cargo.toml README.md src/lib.rs

Use Cases​

Pre-Record Review​

# Make changes
vim src/main.rs src/lib.rs

# Review all changes
atomic diff

# Review specific file
atomic diff src/main.rs

# Record if satisfied
atomic record -m "Update implementation"

Debugging Changes​

# Something broke - check what changed
atomic diff

# Check specific module
atomic diff src/buggy_module.rs

# Investigate further
atomic log --files

Selective Recording​

# Check changes
atomic diff

# Record only some files
atomic record -m "Update config" config.toml

# Check remaining changes
atomic diff

Code Review​

# Review before committing
atomic diff | less

# Save diff for review
atomic diff > review.patch

# Share diff with team
atomic diff --color never | mail -s "Review" team@example.com

Integration with Tools​

With Pager​

# Automatically uses $PAGER (e.g., less)
atomic diff

# Pipe to specific pager
atomic diff | less -R  # -R preserves colors
atomic diff | more

With External Diff Tools​

# Save diff and open in tool
atomic diff > /tmp/changes.diff
code /tmp/changes.diff

# Or use external diff viewer
atomic diff --color never | meld - /dev/null

With Git-style Tools​

# Many git diff tools work with atomic diff
atomic diff | diff-so-fancy
atomic diff | delta

Performance​

Diff computation is generally fast:

  • Small changes (< 10 files): < 50ms
  • Medium changes (10-100 files): < 500ms
  • Large changes (100+ files): < 5 seconds

Performance factors:

  • Number of files changed
  • Size of files
  • Algorithm choice (Myers vs. Patience)
  • Amount of context requested

Notes​

  • Working Copy Only: Diff shows changes in the working copy, not between recorded changes
  • No Staging: Since Atomic has no staging area, diff shows exactly what will be recorded
  • Binary Detection: Binary files are automatically detected and not shown line-by-line
  • Symlinks: Symlink changes are shown as added/deleted links
  • Permissions: Permission changes are tracked and displayed
  • Encodings: Atomic handles various text encodings automatically

Diff Between Changes​

To see differences between recorded changes (not working copy), use:

# Show what a specific change did
atomic change <HASH> --diff

# Compare stack states (advanced)
atomic log --description --files

Configuration​

Relevant configuration options:

# In .atomic/config.toml or ~/.config/atomic/config.toml

[diff]
# Default context lines
context = 3

# Default algorithm
algorithm = "myers"  # or "patience"

# Color output
colors = "auto"  # "auto", "always", or "never"

[colors]
# Customize diff colors
added = "green"
removed = "red"
context = "white"

Environment Variables​

  • PAGER - Pager program for long output (e.g., less -R)
  • NO_COLOR - Disable colored output if set
  • ATOMIC_DIFF_ALGORITHM - Default diff algorithm (myers or patience)

Exit Codes​

  • 0 - Success (no changes or diff displayed successfully)
  • 1 - Error or changes present (depending on context)
  • 2 - Invalid arguments

See Also​

  • Working Copy - Your editable files on disk
  • Pristine - The recorded repository state
  • Diff Algorithms - Myers vs. Patience
  • Hunks - Sections of changes in a diff
  • Context Lines - Unchanged lines shown around changes