Skip to main content

atomic record

Record changes to the repository.

Synopsis​

atomic record [OPTIONS] [FILES]...

Description​

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:

  1. Computes the differences between the working copy and the pristine state
  2. Generates patch operations representing those differences
  3. Creates a change file with metadata (author, timestamp, message)
  4. Applies the change to the current view
  5. Updates the pristine database

To modify an existing change instead of creating a new one, use atomic revise — record always creates a new change.

Arguments​

[FILES]...​

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 .ignore

Options​

-m, --message <MESSAGE>​

Commit message describing the change.

atomic record -m "Add user authentication"

If not provided, Atomic will open your default editor to compose a message.

-a, --all​

Record all changes including untracked files.

atomic record -a -m "Record everything"

--author <AUTHOR>​

Override the author for this change.

atomic record -m "Fix bug" --author "John Doe <john@example.com>"

-i, --identity <IDENTITY>​

Use a specific identity for this change.

atomic record -m "Signed change" --identity work-key

--usage <USAGE>​

Use the default identity for a specific usage context.

atomic record -m "Signed change" --usage signing

-e, --edit​

Open editor for commit message.

atomic record -m "Initial message" --edit

--algorithm <ALGORITHM>​

Diff algorithm to use (default: myers).

atomic record -m "Refactor code" --algorithm myers

--dry-run​

Show what would be recorded without actually recording.

atomic record --dry-run -m "Preview change"

--skip-binary​

Skip binary files instead of failing.

atomic record -m "Add assets" --skip-binary

--max-size <MAX_SIZE>​

Maximum file size to record (in bytes).

atomic record -m "Add data" --max-size 1048576

AI Attribution Options​

Atomic includes first-class support for tracking AI-assisted contributions.

--ai-assisted​

Mark this change as AI-assisted.

atomic record -m "AI generated feature" --ai-assisted

--ai-provider <AI_PROVIDER>​

AI provider/vendor name.

atomic record -m "Feature" --ai-assisted --ai-provider anthropic

--ai-model <AI_MODEL>​

AI model identifier.

atomic record -m "Feature" --ai-assisted --ai-provider anthropic --ai-model claude-opus-4

--ai-tool <AI_TOOL>​

AI tool type.

atomic record -m "Feature" --ai-assisted --ai-tool cursor

--ai-suggestion-type <AI_SUGGESTION_TYPE>​

Type of AI suggestion/contribution.

atomic record -m "Feature" --ai-assisted --ai-suggestion-type collaborative

--ai-input-tokens <AI_INPUT_TOKENS>​

Input tokens used by the AI.

atomic record -m "Feature" --ai-assisted --ai-input-tokens 1200

--ai-output-tokens <AI_OUTPUT_TOKENS>​

Output tokens generated by the AI.

atomic record -m "Feature" --ai-assisted --ai-output-tokens 800

--ai-cost-usd <AI_COST_USD>​

Cost of AI generation in USD.

atomic record -m "Feature" --ai-assisted --ai-cost-usd 0.03

--ai-request-id <AI_REQUEST_ID>​

AI request ID (for auditing).

atomic record -m "Feature" --ai-assisted --ai-request-id req_abc123

--ai-session-id <AI_SESSION_ID>​

AI session/conversation ID.

atomic record -m "Feature" --ai-assisted --ai-session-id sess_xyz789

Global Options​

-v, --verbose​

Emit extra diagnostic output.

--no-color​

Disable ANSI color in output.

-h, --help​

Print help.

-V, --version​

Print version.

Examples​

Basic Recording​

# 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"

Selective Recording​

# 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/

AI-Assisted Changes​

# 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

Custom Author or Identity​

# 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-key

Interactive Editing​

If 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

Working Copy vs. Pristine​

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:

  1. Compares the working copy against the pristine state
  2. Generates patches for the differences
  3. Updates the pristine state with the new change

Change Files​

Recorded changes are stored in .atomic/changes/ with filenames derived from their cryptographic hash:

.atomic/changes/
├── MN/
│   └── YNGT2VGEQZX4QA43FWBDVYQY7CGXN4J2CGE5FDFIHOWQFKFIJQC.change.gz
└── AB/
    └── CDE12345...

Notes​

  • Atomicity: Each record creates 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.

See Also​