Git reference clones and object alternates quick reference¶

Essential commands¶

Goal	Command
Reference clone	`git clone --reference /var/cache/git/repo.git https://forgejo.example.com/org/repo.git dest`
Safe fallback clone	`git clone --reference-if-able /var/cache/git/repo.git https://forgejo.example.com/org/repo.git dest`
Standalone fast clone	`git clone --reference /var/cache/git/repo.git --dissociate https://forgejo.example.com/org/repo.git dest`
Make existing repo standalone	`git repack -a -d -l && rm -f .git/objects/info/alternates`
Inspect active alternates	`cat .git/objects/info/alternates`
Check integrity with alternates	`git fsck --full --strict`

Alternate configuration syntax¶

The file .git/objects/info/alternates lives in .git/objects/info/ and contains newline-separated absolute paths to directory roots:

/var/cache/git/repo-a.git/objects
/var/cache/git/shared-pool.git/objects

Path rules: * Paths must point directly to the objects subdirectory, not the .git root. * Relative paths resolve relative to .git/objects/info/. Absolute paths are recommended to avoid symlink confusion. * Windows paths use forward slashes (C:/cache/git/repo.git/objects).

Environment variables¶

Variable	Description
`GIT_ALTERNATE_OBJECT_DIRECTORIES`	Colon-separated paths to alternate object stores (`/cache/obj1:/cache/obj2`)
`GIT_OBJECT_DIRECTORY`	Override primary write directory for new objects

Reference cache maintenance snippet¶

Add to your CI runner maintenance cron or pipeline runner initialization:

#!/usr/bin/env bash
set -euo pipefail

CACHE_PATH="/var/cache/git/org-repo.git"
REMOTE_URL="https://forgejo.example.com/org/repo.git"

if [ ! -d "$CACHE_PATH" ]; then
  mkdir -p "$(dirname "$CACHE_PATH")"
  git clone --mirror "$REMOTE_URL" "$CACHE_PATH"
else
  # Update refs without deleting objects active builds might borrow
  git --git-dir="$CACHE_PATH" fetch --no-prune origin "+refs/heads/*:refs/heads/*" "+refs/tags/*:refs/tags/*"
fi

Troubleshooting bad object errors¶

If a reference cache is deleted or an alternate path changes, dependent working trees report:

error: unable to read sha1 file of ... (No such file or directory)
fatal: bad object HEAD

To recover:

Restore or fix the path inside .git/objects/info/alternates.

Or fetch the missing objects directly from the origin remote:

git fetch origin --unshallow || git fetch origin "+refs/heads/*:refs/remotes/origin/*"
git repack -a -d
rm -f .git/objects/info/alternates