Skip to main content

atomic reset

Reset the working copy to the last recorded state or switch stacks.

Synopsis​

atomic reset [OPTIONS] [FILES]...

Description​

The reset command restores the working copy to match the pristine state (the last recorded state in the stack). This is useful for:

  • Discarding uncommitted changes: Remove modifications you don't want to keep
  • Switching stacks: Change to a different stack and update the working copy
  • Restoring specific files: Reset individual files while keeping others modified
  • Recovering from conflicts: Reset to a clean state after problematic changes

When you reset, Atomic:

  1. Compares the working copy with the pristine state
  2. Restores files to match the stack state
  3. Discards any unrecorded modifications (unless --force is required)
  4. Optionally switches the current stack

Warning: Reset discards uncommitted changes. They cannot be recovered unless recorded first.

Arguments​

[FILES]...​

Optional paths to reset. If provided, only these files/directories are reset. If omitted, the entire working copy is reset.

# Reset specific file
atomic reset src/main.rs

# Reset directory
atomic reset src/

# Reset multiple files
atomic reset file1.txt file2.txt src/

Options​

--repository <PATH>​

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

atomic reset --repository /path/to/repo

--stack <STACK>​

Reset the working copy to a specific stack and switch to that stack.

# Switch to main stack
atomic reset --stack main

# Switch to feature branch
atomic reset --stack feature/new-ui

--dry-run​

Print a file to standard output without modifying the repository. Works for a single file only.

# Preview what file would look like after reset
atomic reset --dry-run src/main.rs

# Pipe to viewer
atomic reset --dry-run README.md | less

-f, --force​

Reset even if there are unrecorded changes. Required when discarding modifications.

# Force reset with uncommitted changes
atomic reset --force

# Force reset specific file
atomic reset --force src/main.rs

Examples​

Discard All Uncommitted Changes​

# Preview changes that would be lost
atomic diff

# Discard all changes
atomic reset --force

Reset Specific Files​

# Reset single file
atomic reset src/main.rs

# Reset directory
atomic reset tests/

# Reset multiple specific files
atomic reset Cargo.toml README.md src/lib.rs

Switch Stacks​

# Switch to main stack
atomic reset --stack main

# Switch to feature branch and reset working copy
atomic reset --stack feature/auth

Preview File Contents​

# Preview what a file would look like after reset
atomic reset --dry-run src/config.rs

# Compare with current version
atomic reset --dry-run src/config.rs > /tmp/pristine.rs
diff src/config.rs /tmp/pristine.rs

Safe Reset Workflow​

# Check what would be lost
atomic diff

# Optionally save work-in-progress
atomic record -m "WIP: save current state"

# Now reset safely
atomic reset --force

# Or revert to the WIP change later
atomic unrecord  # if needed

Reset vs. Other Commands​

Reset vs. Unrecord​

  • reset: Discards working copy changes, doesn't affect recorded history
  • unrecord: Removes changes from stack history, preserves working copy
# Discard uncommitted changes
atomic reset --force

# Remove last recorded change
atomic unrecord

Reset vs. Revert​

Atomic doesn't have a "revert" command because changes can be unrecorded:

# To undo a recorded change:
atomic unrecord HASH...
atomic reset --force  # Update working copy

Stack Switching​

When using --stack to switch stacks:

Without Uncommitted Changes​

# Clean switch
atomic reset --stack feature-branch

Atomic will:

  1. Switch the current stack
  2. Update working copy to match the new stack
  3. Complete without warnings

With Uncommitted Changes​

# Attempt to switch with changes
atomic reset --stack main
# Error: Cannot change stack, as there are unrecorded changes.

Solution:

# Option 1: Record changes first
atomic record -m "Save changes"
atomic reset --stack main

# Option 2: Force discard changes
atomic reset --force --stack main

Partial Stack Difference​

If stacks have diverged, reset updates only affected files:

# Switch to stack with different files
atomic reset --stack experimental

# Only files that differ between stacks are updated
# Other files remain unchanged

Reset Behavior​

Full Reset (No Files Specified)​

atomic reset --force

Restores the entire working copy:

  • Modified files are reverted
  • Added files (untracked) remain
  • Tracked files are restored to pristine state

Partial Reset (Files Specified)​

atomic reset src/main.rs

Only specified files are reset:

  • Other modifications remain intact
  • Only listed files/directories are restored

Dry Run​

atomic reset --dry-run file.txt > /tmp/pristine.txt
  • Doesn't modify any files
  • Outputs pristine version to stdout
  • Works for exactly one file
  • Useful for previewing changes

Configuration​

Relevant configuration options:

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

# Control reset behavior with changes
reset_overwrites_changes = "auto"  # "auto", "always", or "never"

Options:

  • "never" - Always require --force to discard changes
  • "auto" or "always" - Allow reset to discard changes without --force (default)

Performance​

Reset performance depends on:

  • Working copy size: More files = longer reset
  • Number of files to reset: Fewer files = faster
  • Stack differences: Bigger differences = more work

Typical reset times:

  • Small reset (< 10 files): < 100ms
  • Medium reset (10-100 files): < 1 second
  • Full reset (entire repository): 1-10 seconds

Use Cases​

Experimenting Safely​

# Make experimental changes
vim src/experimental.rs

# Test them
cargo test

# Discard if they don't work
atomic reset --force

Recovering from Mistakes​

# Accidentally modified many files
atomic diff  # Oh no, too many changes!

# Reset to clean state
atomic reset --force

Cleaning Up Merge Conflicts​

# After pull, conflicts appear
atomic pull
# Warning: Conflicts detected

# Reset to pre-pull state
atomic reset --force

# Or reset just conflicted files
atomic reset src/conflicted.rs

File Recovery​

# Accidentally deleted a file
rm important.txt

# Recover it
atomic reset important.txt

Conflicts After Reset​

In rare cases, reset might produce conflicts in the working copy:

Warning: Conflicts detected in working copy
  - src/main.rs

This happens when:

  • Stack has conflicting changes
  • Working copy state is complex

Resolution:

# View conflicts
atomic diff

# Manually resolve
vim src/main.rs

# Record resolution
atomic record -m "Resolve conflicts"

Notes​

  • Destructive: Reset discards uncommitted changes permanently
  • Working Copy Only: Doesn't affect recorded history
  • Selective: Can reset individual files
  • Stack Switching: Updates working copy when changing stacks
  • Safe by Default: Warns before discarding changes (unless configured otherwise)
  • Dry Run: Preview changes without modifying files

Best Practices​

Always Check First​

# Review what will be lost
atomic diff

# Then reset
atomic reset --force

Save Important Work​

# If unsure, record first
atomic record -m "WIP: experimental changes"

# Now safe to reset
atomic reset --force

# Can unrecord later if needed
atomic unrecord

Selective Reset​

# Reset only what's needed
atomic reset src/broken_module.rs

# Keep other changes
atomic diff  # Shows remaining modifications

Exit Codes​

  • 0 - Success
  • 1 - Error (no stack, conflicts, etc.)
  • 2 - Invalid arguments

See Also​

  • Working Copy - Your editable files on disk
  • Pristine - The recorded repository state
  • Stacks - Independent lines of development
  • Uncommitted Changes - Modifications not yet recorded
  • Destructive Operation - Cannot be undone