Git Operations in Atlantis#

Overview#

All git operations in Atlantis are handled by FileWorkspace, which implements the WorkingDir interface in server/events/working_dir.go. FileWorkspace manages cloning, updating, divergence detection, and cleanup of per-PR working directories. The two checkout strategies it supports — branch and merge — drive all downstream git logic.

Checkout Strategies#

FileWorkspace.CheckoutMerge selects the strategy:

Branch strategy (CheckoutMerge=false): shallow-clones the PR head branch at depth 1. No divergence detection runs.
Merge strategy (CheckoutMerge=true): clones the base branch, then merges the PR head into it so Atlantis always plans against the post-merge state. All divergence and prune logic applies to this mode.

Key Entry Points#

Method	Purpose
`Clone`	Initial checkout; uses fast path (read lock + `git rev-parse`) to skip re-cloning if already at the right commit
`MergeAgain`	Re-merges when the base branch has advanced; uses leader/follower pattern to avoid write-lock contention
`HasDiverged`	Checks if base branch has new commits; only active when `CheckoutMerge=true`
`GetDivergedFiles`	Returns files changed by divergent base commits (for `when_modified` targeting)
`updateToRef`	Updates an existing clone to a new commit; redoes the merge under merge strategy
`mergeToBaseBranch`	Core merge routine: fetch PR head → check merge base → `git merge --no-ff`

Merge Checkout Strategy Flow#

forceClone implements the initial merge checkout:

Removes and recreates the clone directory.
Clones the base branch (with optional CheckoutDepth for shallow clones) .
Adds the PR head as the source remote when usesPRSourceRemote is true (non-GitHub-App path) .
Calls mergeToBaseBranch, which:
- Fetches the PR head: pull/<N>/head from origin for GitHub App; +refs/heads/<branch>: from source remote otherwise .
- Checks for a merge base; if not found (shallow clone too shallow), falls back to git fetch --unshallow .
- Runs git merge -q --no-ff -m "atlantis-merge" FETCH_HEAD. --no-ff forces a merge commit so git rev-parse HEAD^2 reliably returns the PR head commit .

For existing clones, updateToRef re-does the merge:

git reset --hard origin/<base-branch>
Calls mergeToBaseBranch again.
Verifies HEAD^2 matches the expected targetRef.
Calls cleanStalePlanFiles to remove untracked .tfplan files via git clean -f -x -e .terragrunt-cache -- ':(glob)**/*.tfplan' (since git reset --hard leaves untracked files behind).

When the base branch advances after an initial clone, MergeAgain triggers a re-merge via mergeAgain: reset to refs/remotes/origin/<base-branch>, then call mergeToBaseBranch.

Branch Retargeting#

If remoteHasBranch finds that the base branch no longer exists in the remote (e.g., the PR was retargeted to a different base), attemptReuseCloneDir returns false and forces a full reclone .

Divergence Detection#

Only active when CheckoutMerge=true. Key internal functions:

hasDiverged: runs git fetch then git status --untracked-files=no; checks for "have diverged" in output. Returns true on any error (fail-safe).
getDivergedFilesFromRef: runs git fetch then git log <startRef>..<origin/base-branch> --name-only --format= to find files changed by commits the workspace hasn't seen.
hasDivergedForPatterns: used when autoplanWhenModified patterns are set. Gets the diverged file list, filters it through patternmatcher, and reports divergence only if at least one file matches.
recheckDiverged: called by MergeAgain. Refreshes remote URLs (to handle expired GitHub App credentials), runs git remote update [--prune] or git remote update origin [--prune], then delegates to hasDiverged. Returns true on any error.

Error Propagation (PR #6632)#

PR #6632 fixed a bug where fetch errors in divergence checks were silently swallowed and treated as "assume divergence," allowing plans to proceed against a potentially stale workspace. After the fix, fetch failures abort the plan/apply operation via the command requirement handler.

Stale Remote-Tracking Ref Pruning (PR #6631)#

Problem: Without pruning, if a remote branch is deleted or renamed, its stale remote-tracking ref (e.g., refs/remotes/origin/feature/foo) remains as a directory entry under .git/refs/remotes/. If a new branch is later created whose name occupies the same path prefix (e.g., origin/feature), git fails with cannot lock ref / exists; cannot create. Previously, recheckDiverged treated this fetch failure as "assume divergence" and swallowed the error.

Fix (PR #6631): --prune was added to all git fetch/update operations in working_dir.go:

Location	Before	After
`recheckDiverged` (non-App path)	`git remote update`	`git remote update --prune`
`recheckDiverged` (origin-only)	`git remote update origin`	`git remote update origin --prune`
`hasDiverged`	`git fetch`	`git fetch --prune`
`getDivergedFilesFromRef`	`git fetch`	`git fetch --prune`
`updateToRef` (all remotes)	`fetch --all`	`fetch --all --prune`
`updateToRef` (origin-only)	`fetch origin`	`fetch origin --prune`
`mergeToBaseBranch` (unshallow)	`fetch --unshallow`	`fetch --unshallow --prune`

A regression test TestMergeAgain_PrunesConflictingRefNames in working_dir_test.go reproduces and verifies the fix.

Locking Model#

FileWorkspace uses a sync.Map called gitLocks with two key namespaces :

repo-lock/<cloneDir> → *sync.RWMutex. Write-locked by Clone, MergeAgain, and updateToRef; read-locked by HasDiverged, HasDivergedFromPullHead, GetDivergedFiles, recheckDiverged, and plan/apply step execution via GitReadLock.
ref-lock/<cloneDir> → *sync.Mutex. Serializes fetch and remote-update operations independently to reduce contention.

The read lock is always acquired before the ref lock to avoid deadlock .

Concurrent Merge Coordination#

MergeAgain uses a pendingMerge value in a pendingMerges sync.Map to avoid multiple goroutines serializing on the write lock. The first goroutine (leader) acquires the write lock and performs the merge; others wait on a done channel and reuse the leader's result . The pendingMerge entry is closed and deleted while the write lock is still held, preventing new callers from joining a stale completed merge .