Skip to main content

Git Workflow Resilience

AGIT automatically handles complex Git workflows to keep your neural context in sync. This guide explains the resilience mechanisms that protect your reasoning history.

Overview​

When using Git, several operations can disrupt the link between code and context:

ScenarioProblemAGIT Solution
git commit --amendHash changes, context appears lostDetects amend, migrates context
git reset --hardHistory rewound, context orphanedSnaps to valid ancestor
git checkout branchWrong context loadedPer-branch context stashing
git merge / git rebaseConflicted stateBlocks mutations until resolved

Merge & Rebase Guard​

During a merge or rebase, Git is in an unstable state. AGIT blocks mutating commands to prevent graph corruption.

How It Works​

AGIT detects conflicted state by checking:

  • .git/MERGE_HEAD (merge in progress)
  • .git/rebase-merge/ or .git/rebase-apply/ (rebase in progress)

What Gets Blocked​

When in a conflicted state, these commands are blocked:

  • agit record
  • agit add
  • agit commit

You'll see an error like:

⚠️  Merge in progress. Please resolve conflicts and finish the Merge before adding neural memories.

Status Warning​

agit status shows a warning but still works:

agit status
⚠️  Merge in progress. Agit is in read-only mode.
   Resolve conflicts and run 'git merge --continue' first.

Branch: main
No pending entries

Resolution​

  1. Resolve Git conflicts normally
  2. Run git merge --continue or git rebase --continue
  3. AGIT commands work again

Amend Detection​

When you run git commit --amend, Git replaces the commit with a new hash. Without detection, AGIT would think history was lost.

How It Works​

AGIT compares the old and new commits using a heuristic:

  1. Same author email
  2. Same commit message (first line)
  3. Timestamp within 60 seconds

If all three match, it's treated as an amend rather than a rewind.

Automatic Migration​

When an amend is detected:

🔄 Detected git amend. Migrated memory to new hash.
   New git hash: abc1234
   New neural hash: def5678

The neural commit is updated to point to the new Git hash. Your context history remains intact.

Example​

# Create a commit with context
agit record "Implementing user auth"
git add .
git commit -m "Add user authentication"
agit commit -m "User authentication feature"

# Amend the Git commit
git commit --amend -m "Add user authentication"

# AGIT automatically migrates
agit status
# 🔄 Detected git amend. Migrated memory to new hash.

Per-Branch Context​

When you switch branches, AGIT preserves your pending thoughts for each branch separately.

How It Works​

On branch switch:

  1. Stash current branch's pending thoughts to .agit/stash/<branch>/index
  2. Restore target branch's pending thoughts (or clear if none)

Example​

# On main branch, record some thoughts
agit record "Planning auth refactor"
agit status
# 1 entry pending

# Switch to feature branch
git checkout feature-x
agit status
# No pending entries (feature-x has no stashed context)

# Work on feature branch
agit record "Adding new API endpoint"

# Switch back to main
git checkout main
agit status
# 1 entry pending (restored from stash)
# "Planning auth refactor" is back

Storage​

Stashed contexts are stored in:

.agit/
├── index              # Current branch's pending thoughts
└── stash/
    ├── main/index     # Stashed for 'main'
    ├── feature-x/index
    └── bugfix/index

Rewind Recovery​

When you run git reset --hard or otherwise rewind history, AGIT snaps back to a valid ancestor.

How It Works​

  1. AGIT checks if its linked Git commit is still reachable
  2. If not reachable, walks backwards through neural history
  3. Finds the nearest neural commit that links to a valid Git commit
  4. Updates the branch ref to point there

Example​

# You have 5 commits with context
agit log
# abc1234 Latest feature
# def5678 Bug fix
# ghi9012 Refactor
# ...

# Hard reset to 3 commits ago
git reset --hard HEAD~3

# AGIT detects the rewind
agit status
# Warning: Git history rewound. Snapped agit HEAD back to valid ancestor.
#   2 orphaned neural commit(s) left as objects (not deleted).

Orphan Preservation​

Orphaned neural commits are not deleted. They remain in storage and can be recovered if you restore the Git commits via git reflog.

Semantic Conflict Detection​

AGIT prevents "hallucinated" commits when external changes affect files mentioned in your pending thoughts.

How It Works​

Before committing, AGIT:

  1. Detects "ghost commits" (Git commits made outside AGIT)
  2. Extracts file references from your pending thoughts
  3. Checks for overlap between ghost commit files and thought files

Safe vs Unsafe Scenarios​

Safe (auto-proceeds):

Ghost commit modified: README.md
Your thought mentions: src/auth.rs
→ No overlap, commit proceeds

Unsafe (blocks):

Ghost commit modified: src/auth.rs
Your thought mentions: "fixing the auth.rs bug"
→ Overlap detected, blocks commit

Override with --force​

If you're sure the conflict is fine:

agit commit -m "My changes" --force

Status Warning​

agit status warns about potential conflicts:

⚠️  Context conflict detected:
   External commits touched files mentioned in your thoughts:
   - src/auth.rs

   Use 'agit commit --force' to proceed, or 'agit reset' to clear thoughts.

Best Practices​

Before Major Git Operations​

Check your pending context:

agit status
# If you have pending thoughts, commit them first
agit commit -m "Work in progress"

During Long-Running Branches​

Commit context regularly:

# Don't let thoughts pile up across many Git commits
agit commit -m "Context checkpoint"

After Rebase/Merge​

Verify your context is still intact:

agit log --limit 3
agit status

Next Steps​