| sidebar_position | 3 |
|---|---|
| title | record |
Record changes to the repository.
atomic record [OPTIONS] [FILES]...The record command is the primary way to save your work in Atomic. It examines the differences between your working copy and the current state of the view, then creates a new change containing those modifications.
Unlike traditional version control systems that record snapshots, Atomic records semantic patches — the actual operations performed on files (additions, deletions, modifications). This enables Atomic's powerful conflict-free merging and mathematical correctness guarantees.
When you record a change, Atomic:
- Computes the differences between the working copy and the pristine state
- Generates patch operations representing those differences
- Creates a change file with metadata (author, timestamp, message)
- Applies the change to the current view
- Updates the pristine database
To modify an existing change instead of creating a new one, use atomic revise — record always creates a new change.
Specific files to record. If provided, only changes within these paths will be recorded. Paths are relative to the repository root.
# Record only changes in src/
atomic record -m "Update source" src/
# Record multiple specific paths
atomic record -m "Update configs" config.toml .ignoreCommit message describing the change.
atomic record -m "Add user authentication"If not provided, Atomic will open your default editor to compose a message.
Record all changes including untracked files.
atomic record -a -m "Record everything"Override the author for this change.
atomic record -m "Fix bug" --author "John Doe <john@example.com>"Use a specific identity for this change.
atomic record -m "Signed change" --identity work-keyUse the default identity for a specific usage context.
atomic record -m "Signed change" --usage signingOpen editor for commit message.
atomic record -m "Initial message" --editDiff algorithm to use (default: myers).
atomic record -m "Refactor code" --algorithm myersShow what would be recorded without actually recording.
atomic record --dry-run -m "Preview change"Skip binary files instead of failing.
atomic record -m "Add assets" --skip-binaryMaximum file size to record (in bytes).
atomic record -m "Add data" --max-size 1048576Record files even if they still contain unresolved conflict markers. Off by default — a recording that embeds <<<<<<< markers is usually a mistake, so Atomic refuses it unless you pass this flag explicitly.
atomic record -m "Merge resolution" --allow-conflict-markers:::caution Only use this when you have genuinely resolved a conflict but want to keep marker-like content (e.g. in test fixtures or docs about conflict markers). :::
Atomic includes first-class support for tracking AI-assisted contributions.
Mark this change as AI-assisted.
atomic record -m "AI generated feature" --ai-assistedAI provider/vendor name.
atomic record -m "Feature" --ai-assisted --ai-provider anthropicAI model identifier.
atomic record -m "Feature" --ai-assisted --ai-provider anthropic --ai-model claude-opus-4AI tool type.
atomic record -m "Feature" --ai-assisted --ai-tool cursorType of AI suggestion/contribution.
atomic record -m "Feature" --ai-assisted --ai-suggestion-type collaborativeInput tokens used by the AI.
atomic record -m "Feature" --ai-assisted --ai-input-tokens 1200Output tokens generated by the AI.
atomic record -m "Feature" --ai-assisted --ai-output-tokens 800Cost of AI generation in USD.
atomic record -m "Feature" --ai-assisted --ai-cost-usd 0.03AI request ID (for auditing).
atomic record -m "Feature" --ai-assisted --ai-request-id req_abc123AI session/conversation ID.
atomic record -m "Feature" --ai-assisted --ai-session-id sess_xyz789Emit extra diagnostic output.
Disable ANSI color in output.
Print help.
Print version.
# Record with a message
atomic record -m "Add new feature"
# Record all changes, including untracked files
atomic record -a -m "Record everything"
# Preview what would be recorded without committing
atomic record --dry-run -m "Preview change"# Record only changes in the src/ directory
atomic record -m "Update source files" src/
# Record changes in multiple paths
atomic record -m "Config updates" config/ docs/# Simple AI attribution
atomic record -m "Generate API client" --ai-assisted
# Detailed AI attribution
atomic record -m "Implement feature" \
--ai-assisted \
--ai-provider anthropic \
--ai-model claude-opus-4 \
--ai-tool cursor \
--ai-suggestion-type collaborative \
--ai-input-tokens 1200 \
--ai-output-tokens 800# Record with a custom author
atomic record -m "Pair programming changes" --author "Alice & Bob <team@example.com>"
# Record signed with a specific identity
atomic record -m "Signed change" --identity work-keyIf you don't provide a message with -m, Atomic will open your default editor (configured via $EDITOR or $VISUAL) to compose the change message:
# Please enter the change message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the recording.
#
# Changes to be recorded:
# modified: src/main.rs
# added: src/new_module.rs
# deleted: src/old_file.rs
Atomic maintains two key concepts:
- Working Copy: Your actual files on disk that you edit
- Pristine: The database representation of the repository state
When you run record, Atomic:
- Compares the working copy against the pristine state
- Generates patches for the differences
- Updates the pristine state with the new change
Recorded changes are stored in .atomic/changes/ with filenames derived from their cryptographic hash:
.atomic/changes/
├── MN/
│ └── YNGT2VGEQZX4QA43FWBDVYQY7CGXN4J2CGE5FDFIHOWQFKFIJQC.change.gz
└── AB/
└── CDE12345...
- Atomicity: Each
recordcreates one indivisible change. All modifications are recorded together or not at all. - Immutability: Once recorded, changes are immutable and cryptographically identified by their hash. To modify a recorded change, use
atomic revise. - No Staging: Atomic doesn't have a staging area. Changes are recorded directly from the working copy.
- Partial Recording: Pass file arguments to record only specific files or directories.
- Empty Changes: Atomic will refuse to record if there are no changes in the working copy.
atomic status- Show the state of the working copy before recordingatomic diff- Preview changes before recordingatomic revise- Modify an existing changeatomic log- View recorded changesatomic add- Start tracking new files