Migrating from Git to Atomic

Welcome, Git users! This guide will help you transition from Git to Atomic VCS. While both are distributed version control systems, Atomic offers unique features like conflict-free merging, AI attribution, and consolidating tags that fundamentally change how you work with code.

Quick Start: Import Your Git Repository

The fastest way to get started is to import your existing Git repository:

# Navigate to your Git repository
cd /path/to/your/git/repo

# Import into Atomic (creates .atomic directory)
atomic git

# Start using Atomic!
atomic log

That's it! Atomic will:

Import your entire Git history
Convert commits to Atomic changes
Preserve author information and timestamps
Create equivalent branches as stacks
Maintain your working copy

Understanding the Differences

Terminology Mapping

Git Term	Atomic Term	Notes
Commit	Change	Immutable semantic patches
Branch	Stack	Independent lines of development
Merge	Pull/Apply	Conflict-free by design
Tag	Tag	Consolidating boundaries (more powerful!)
Remote	Remote	Same concept
Staging Area	(none)	No staging - direct recording
HEAD	Current Stack	Explicit stack selection
Working Directory	Working Copy	Your editable files

Key Conceptual Differences

Critical Understanding: Atomic stacks are fundamentally different from Git branches.

Git branches: Each branch switch changes your working directory to match that branch's state.

Atomic stacks: All stacks share the same working copy. Only the patch history is isolated.

Concrete Example

# Start on main stack
atomic stack switch main
ls
# Output: test.txt

# Create and switch to new stack
atomic stack new new-feature
atomic stack switch new-feature

# Create and record a new file
vi new-file.txt
atomic record new-file.txt -m "Add new feature"

# Switch back to main
atomic stack switch main
ls
# Output: new-file.txt test.txt
#         ^^^^^^^^^^^^
#         STILL HERE! (untracked from main's perspective)

Why does new-file.txt appear on main?

It's recorded on new-feature stack (in patch history) ✅
But it's untracked from main's perspective (not recorded on main)
Atomic doesn't delete untracked files when switching stacks
The patch history is isolated, but the working copy is shared

What IS Isolated Between Stacks?

# Patch history is isolated
atomic stack switch main
atomic log              # Does NOT show "Add new feature"

atomic stack switch new-feature
atomic log              # DOES show "Add new feature"

Mental Model

Git:
  main branch    → working dir state A
  feature branch → working dir state B

Atomic:
  main stack    → patch history A  }
  feature stack → patch history B  } → SAME working copy

Think of stacks as different views of patch history, NOT different workspaces.

2. No Merge Conflicts

Git: Merge conflicts require manual resolution

git merge feature
# CONFLICT (content): Merge conflict in file.txt
# Automatic merge failed; fix conflicts and then commit the result.

Atomic: Mathematically guaranteed conflict-free merging

atomic pull . --from-stack feature
# Changes applied successfully (no conflicts ever!)

Why? Atomic uses patch theory - changes are semantic operations, not text diffs.

3. No Staging Area

Git: Requires staging before commit

git add file1.txt file2.txt
git commit -m "Update files"

Atomic: Direct recording from working copy

atomic record -m "Update files"
# All tracked changes are recorded

To record specific files:

atomic record -m "Update config" config.toml

4. Consolidating Tags

Git: Tags are just pointers to commits

git tag v1.0.0

Atomic: Tags consolidate dependencies (revolutionary!)

atomic tag create v1.0.0 -m "First release"
# Reduces O(n²) to O(n) complexity
# Dramatically improves performance at scale

Atomic tags are first-class nodes in the dependency graph, enabling:

96% reduction in dependency complexity
Efficient hotfix workflows
Mathematical semantic guarantees

5. Changes vs Commits

Git commits are snapshots of the entire repository at a point in time.

Atomic changes are semantic patch operations:

Represent the actual operations performed
Can be applied in any order (commutative)
Enable conflict-free merging
Cryptographically identified by content

Command Translation Guide

Repository Setup

# Git
git init
git clone https://github.com/user/repo.git

# Atomic
atomic init
atomic clone ssh://github.com/user/repo.git

Basic Workflow

# Git
git add .
git commit -m "Add feature"
git push origin main

# Atomic
atomic add .
atomic record -m "Add feature"
atomic push origin

Viewing History

# Git
git log
git log --oneline
git log --graph --all

# Atomic
atomic log
atomic log --limit 10
atomic log --state  # Shows state hashes (Merkle trees)

Branching

# Git
git branch feature-branch
git checkout feature-branch
git checkout -b new-feature

# Atomic
atomic stack new feature-branch
atomic stack switch feature-branch
# Or combine: atomic stack new feature-branch && atomic stack switch feature-branch

⚠️ Important: Unlike git checkout, atomic stack switch does NOT change untracked files in your working copy. Stacks share the same workspace - only the patch history is isolated. See Stacks Share Working Copy above for details.

Merging

# Git
git checkout main
git merge feature-branch

# Atomic
atomic stack switch main
atomic pull . --from-stack feature-branch
# No merge conflicts - mathematically guaranteed!

Viewing Changes

# Git
git diff
git diff --staged
git show commit-hash

# Atomic
atomic diff
# (No staging area needed)
atomic change CHANGE-HASH --diff

Undoing Changes

# Git
git reset --hard HEAD
git reset HEAD~1
git revert commit-hash

# Atomic
atomic reset --force              # Discard working copy changes
atomic unrecord                   # Remove recorded changes
atomic unrecord CHANGE-HASH       # Remove specific change

Remote Operations

# Git
git remote add origin url
git fetch origin
git pull origin main
git push origin main

# Atomic
# Edit .atomic/config.toml to add remote
atomic pull origin
atomic pull origin --from-stack main
atomic push origin

Tagging

# Git
git tag v1.0.0
git tag -a v1.0.0 -m "Release 1.0"

# Atomic
atomic tag create v1.0.0 -m "Release 1.0"
# This also consolidates dependencies!

Stashing (Atomic Equivalent)

# Git
git stash
git stash pop

# Atomic (record as WIP)
atomic record -m "WIP: save work"
# ... do other work ...
atomic unrecord  # Remove WIP change, keeps working copy

Importing Git History

Full Repository Import

# Import entire Git history
cd your-git-repo
atomic git

# Verify import
atomic log --limit 10
atomic stack list

Import Specific Paths

# Import Git repo from different location
atomic git /path/to/git/repo /path/to/atomic/repo

What Gets Imported

✅ Imported:

All commits as Atomic changes
Commit messages and descriptions
Author information and timestamps
Branch structure (as stacks)
Tags (as Atomic tags)
File history

❌ Not Imported:

Git-specific metadata
Merge commit structure (converted to changes)
Submodules (requires manual handling)
Git hooks (reimplement in Atomic)

Post-Import Steps

After importing:

# 1. Verify the import
atomic log --limit 20
atomic stack list

# 2. Create a consolidating tag for better performance
atomic tag create v1.0.0 -m "Initial import from Git"

# 3. Set up your remotes
# Edit .atomic/config.toml:
# [remote "origin"]
# ssh = "ssh://git@github.com/user/repo.git"

# 4. Continue with Atomic
atomic record -m "First Atomic change"
atomic push

Workflow Comparison

Git Workflow

# Feature branch workflow
git checkout -b feature/auth
# ... make changes ...
git add .
git commit -m "Add authentication"
git push origin feature/auth

# Create PR, get review, merge
git checkout main
git pull origin main
git merge feature/auth
# Resolve conflicts if any
git push origin main

# Tag release
git tag v1.0.0
git push origin v1.0.0

Atomic Workflow

# Feature stack workflow
atomic stack new feature/auth
atomic stack switch feature/auth
# ... make changes ...
atomic record -m "Add authentication"
atomic push --from-stack feature/auth

# Review, then merge (no conflicts!)
atomic stack switch main
atomic pull . --from-stack feature/auth
atomic push

# Tag release (with consolidation!)
atomic tag create v1.0.0 -m "First release"
atomic push --with-tags

Advanced Features for Git Users

1. AI Attribution (Not Available in Git)

Track AI contributions cryptographically:

# Record AI-assisted change
atomic record -m "AI generated feature" \
  --ai-assisted \
  --ai-provider cursor \
  --ai-model gpt-4 \
  --ai-confidence 0.95

# View AI contributions
atomic log --attribution --ai-only

2. Consolidating Tags (Revolutionary)

Unlike Git tags, Atomic tags reduce dependency complexity:

# Create consolidating tag
atomic tag create v1.0.0 -m "Major release"

# Now future changes depend on the tag, not all prior changes
# Result: 96% reduction in dependencies!

3. Conflict-Free Distributed Collaboration

Multiple developers can work simultaneously without conflicts:

# Alice and Bob both work on main
# Alice: atomic record -m "Add feature A"
# Bob:   atomic record -m "Add feature B"

# Both push
# Alice: atomic push
# Bob:   atomic push

# Bob pulls Alice's work - no conflicts!
# Bob:   atomic pull
# Result: Both changes applied correctly (mathematical guarantee)

4. Stack Independence

Stacks are truly independent (unlike Git branches):

# Work on multiple features simultaneously
atomic stack new feature-1
atomic record -m "Work on feature 1"

atomic stack new feature-2
atomic record -m "Work on feature 2"

# Apply changes between stacks
atomic stack switch main
atomic pull . --from-stack feature-1
atomic pull . --from-stack feature-2
# No merge conflicts!

Configuration for Git Users

Setting Up Your Identity

# Similar to git config
atomic identity new default \
  --username yourname \
  --display-name "Your Name" \
  --email your.email@example.com

# Or use existing Git config
# Atomic reads from .atomic/config.toml:

Example .atomic/config.toml:

[author]
username = "yourname"
display_name = "Your Name"

[remote "origin"]
ssh = "ssh://git@github.com/user/repo.git"

[identity]
default = "default"

Remotes Configuration

# Multiple remotes (like Git)
[remote "origin"]
ssh = "ssh://git@github.com/user/repo.git"

[remote "upstream"]
ssh = "ssh://git@github.com/original/repo.git"

[remote "backup"]
ssh = "ssh://backup@server.com/repos/project.git"

Common Git Scenarios in Atomic

Scenario 1: Feature Branch Workflow

Git:

git checkout -b feature
# work...
git add .
git commit -m "Feature"
git checkout main
git merge feature
# resolve conflicts
git branch -d feature

Atomic:

atomic stack new feature
# work...
atomic record -m "Feature"
atomic stack switch main
atomic pull . --from-stack feature
# no conflicts!
atomic stack delete feature

Scenario 2: Hotfix Workflow

Git:

git checkout -b hotfix v1.0.0
# fix bug...
git commit -m "Hotfix"
git tag v1.0.1
git checkout main
git merge hotfix

Atomic (Revolutionary!):

# Checkout tag to new stack
atomic tag checkout v1.0.0 --to-stack hotfix
atomic stack switch hotfix
# fix bug...
atomic record -m "Hotfix"

# Create incremental tag (only depends on v1.0.0!)
atomic tag create v1.0.1 --since v1.0.0 -m "Hotfix"

# Merge back to main
atomic stack switch main
atomic pull . --from-stack hotfix

Scenario 3: Rebasing (Not Needed!)

Git:

git checkout feature
git rebase main  # Can cause conflicts

Atomic:

# Just pull changes - no rebasing needed!
atomic stack switch feature
atomic pull . --from-stack main
# Conflict-free!

Performance at Scale

Git Performance Issues

O(n²) history growth with merges
Merge conflicts increase with project size
Large repositories become slow

Atomic Performance Benefits

O(n) history growth with tags
No merge conflicts (mathematical guarantee)
Consolidating tags keep repos fast

Example with 100 changes:

Git: ~5,050 potential merge points
Atomic with tags: ~200 dependencies (96% reduction!)

Migration Checklist

Troubleshooting

Import Issues

Problem: Import fails with "uncommitted changes"

# Solution: Commit or stash in Git first
git status
git commit -am "Pending changes"
atomic git

Working Copy Differences

Problem: Files look different after import

# Solution: Reset working copy
atomic reset --force

Remote Push Issues

Problem: Can't push to Git remotes

# Atomic uses its own protocol
# Set up Atomic-compatible remotes
# Or use Git as a bridge (advanced)

Getting Help

Documentation: docs.atomic.dev
Discord: discord.gg/atomic-vcs
GitHub Issues: github.com/atomic-vcs/atomic/issues
Community Forum: community.atomic.dev

Next Steps

Import your Git repository: atomic git
Create your first change: atomic record -m "First Atomic change"
Explore AI attribution: atomic record --ai-assisted
Create consolidating tags: atomic tag create v1.0.0
Experience conflict-free merging: Try parallel development!

Why Switch from Git?

Key Advantages

✅ No Merge Conflicts - Mathematical guarantees
✅ AI Attribution - Cryptographic tracking of AI contributions
✅ Consolidating Tags - O(n) instead of O(n²) complexity
✅ Semantic Patches - Operations, not text diffs
✅ True Distribution - Every repo is complete and independent
✅ Production Ready - Enterprise workflow integration

Welcome to the future of version control! 🚀

Ready to make the switch? Import your first Git repository and experience conflict-free development:

cd your-git-repo
atomic git
atomic log

Quick Start: Import Your Git Repository​

Understanding the Differences​

Terminology Mapping​

Key Conceptual Differences​

1. Stacks Share Working Copy (NOT Like Git Branches!)​

Concrete Example​

What IS Isolated Between Stacks?​

Mental Model​

2. No Merge Conflicts​

3. No Staging Area​

4. Consolidating Tags​

5. Changes vs Commits​

Command Translation Guide​

Repository Setup​

Basic Workflow​

Viewing History​

Branching​

Merging​

Viewing Changes​

Undoing Changes​

Remote Operations​

Tagging​

Stashing (Atomic Equivalent)​

Importing Git History​

Full Repository Import​

Import Specific Paths​

What Gets Imported​

Post-Import Steps​

Workflow Comparison​

Git Workflow​

Atomic Workflow​

Advanced Features for Git Users​

1. AI Attribution (Not Available in Git)​

2. Consolidating Tags (Revolutionary)​

3. Conflict-Free Distributed Collaboration​

4. Stack Independence​

Configuration for Git Users​

Setting Up Your Identity​

Remotes Configuration​

Common Git Scenarios in Atomic​

Scenario 1: Feature Branch Workflow​

Scenario 2: Hotfix Workflow​

Scenario 3: Rebasing (Not Needed!)​

Performance at Scale​

Git Performance Issues​

Atomic Performance Benefits​

Migration Checklist​

Troubleshooting​

Import Issues​

Working Copy Differences​

Remote Push Issues​

Getting Help​

Next Steps​

Why Switch from Git?​

Key Advantages​

Quick Start: Import Your Git Repository

Understanding the Differences

Terminology Mapping

Key Conceptual Differences

1. Stacks Share Working Copy (NOT Like Git Branches!)

Concrete Example

What IS Isolated Between Stacks?

Mental Model

2. No Merge Conflicts

3. No Staging Area

4. Consolidating Tags

5. Changes vs Commits

Command Translation Guide

Repository Setup

Basic Workflow

Viewing History

Branching

Merging

Viewing Changes

Undoing Changes

Remote Operations

Tagging

Stashing (Atomic Equivalent)

Importing Git History

Full Repository Import

Import Specific Paths

What Gets Imported

Post-Import Steps

Workflow Comparison

Git Workflow

Atomic Workflow

Advanced Features for Git Users

1. AI Attribution (Not Available in Git)

2. Consolidating Tags (Revolutionary)

3. Conflict-Free Distributed Collaboration

4. Stack Independence

Configuration for Git Users

Setting Up Your Identity

Remotes Configuration

Common Git Scenarios in Atomic

Scenario 1: Feature Branch Workflow

Scenario 2: Hotfix Workflow

Scenario 3: Rebasing (Not Needed!)

Performance at Scale

Git Performance Issues

Atomic Performance Benefits

Migration Checklist

Troubleshooting

Import Issues

Working Copy Differences

Remote Push Issues

Getting Help

Next Steps

Why Switch from Git?

Key Advantages