Appearance
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/objectsPath rules:
- Paths must point directly to the
objectssubdirectory, not the.gitroot. - 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:
bash
#!/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/*"
fiTroubleshooting 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 HEADTo recover:
- Restore or fix the path inside
.git/objects/info/alternates. - Or fetch the missing objects directly from the origin remote:bash
git fetch origin --unshallow || git fetch origin "+refs/heads/*:refs/remotes/origin/*" git repack -a -d rm -f .git/objects/info/alternates