Skip to content

Git reference clones and object alternates quick reference ​

Essential commands ​

GoalCommand
Reference clonegit clone --reference /var/cache/git/repo.git https://forgejo.example.com/org/repo.git dest
Safe fallback clonegit clone --reference-if-able /var/cache/git/repo.git https://forgejo.example.com/org/repo.git dest
Standalone fast clonegit clone --reference /var/cache/git/repo.git --dissociate https://forgejo.example.com/org/repo.git dest
Make existing repo standalonegit repack -a -d -l && rm -f .git/objects/info/alternates
Inspect active alternatescat .git/objects/info/alternates
Check integrity with alternatesgit 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 ​

VariableDescription
GIT_ALTERNATE_OBJECT_DIRECTORIESColon-separated paths to alternate object stores (/cache/obj1:/cache/obj2)
GIT_OBJECT_DIRECTORYOverride 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/*"
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:

  1. Restore or fix the path inside .git/objects/info/alternates.
  2. 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

Git Master — Git Reference for Every Skill Level