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 import

# 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 views
Maintain your working copy

Understanding the Differences

Terminology Mapping

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

Key Conceptual Differences

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

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

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

Concrete Example

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

# Create and switch to new view
atomic view create new-feature
atomic view 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 view 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 view (in patch history) ✅
But it's untracked from main's perspective (not recorded on main)
Atomic doesn't delete untracked files when switching views
The patch history is isolated, but the working copy is shared

What IS Isolated Between Views?

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

atomic view 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 view    → patch history A  }
  feature view → patch history B  } → SAME working copy

Think of views as different perspectives on 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-view 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 view create feature-branch
atomic view switch feature-branch
# Or combine: atomic view create feature-branch && atomic view switch feature-branch

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

Merging

# Git
git checkout main
git merge feature-branch

# Atomic
atomic view switch main
atomic pull . --from-view 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-view 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 import

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

Import Specific Paths

# Import Git repo from different location
atomic git import /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 views)
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 view 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 view workflow
atomic view create feature-auth
atomic view switch feature-auth
# ... make changes ...
atomic record -m "Add authentication"
atomic push --from-view feature-auth

# Review, then merge (no conflicts!)
atomic view switch main
atomic pull . --from-view 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. View Independence

Views are truly independent (unlike Git branches):

# Work on multiple features simultaneously
atomic view create feature-1
atomic record -m "Work on feature 1"

atomic view create feature-2
atomic record -m "Work on feature 2"

# Insert changes between views
atomic view switch main
atomic pull . --from-view feature-1
atomic pull . --from-view 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 view create feature
# work...
atomic record -m "Feature"
atomic view switch main
atomic pull . --from-view feature
# no conflicts!
atomic view 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 view
atomic tag checkout v1.0.0 --to-view hotfix
atomic view 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 view switch main
atomic pull . --from-view hotfix

Scenario 3: Rebasing (Not Needed!)

Git:

git checkout feature
git rebase main  # Can cause conflicts

Atomic:

# Just pull changes - no rebasing needed!
atomic view switch feature
atomic pull . --from-view 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 import

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 import
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 import
atomic log

Quick Start: Import Your Git Repository​

Understanding the Differences​

Terminology Mapping​

Key Conceptual Differences​

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

Concrete Example​

What IS Isolated Between Views?​

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. View 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. Views Share Working Copy (NOT Like Git Branches!)

Concrete Example

What IS Isolated Between Views?

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