Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Files and Formats

The objects/info/alternates file

Reference for objects/info/alternates: borrow objects from another repository to save disk space, how clone --reference and --shared set it up, and the risks.

The file .git/objects/info/alternates lists other object directories that this repository may read from. When Git needs an object it does not have locally, it looks in each listed directory before giving up. Several repositories can then share one large object store, each holding only the objects unique to it. Build farms and hosting services use this to keep dozens of clones of the same project small.

The file has one path per line, pointing at another repository's objects directory. It is a pure read-sharing mechanism: new objects are always written to the repository's own store.

Terminal
echo /srv/mirror/linux.git/objects >> .git/objects/info/alternates

Try it

Bash Clone with reference and shared

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Bash Add an alternate by hand, then stop depending on it

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.

Syntax

Terminal
# .git/objects/info/alternates
/absolute/path/to/other/objects
../relative/to/this/objects
# comments are allowed
Mechanism Effect
File objects/info/alternates One object directory per line; absolute or relative to this repository's objects directory. Lines starting with # are ignored.
GIT_ALTERNATE_OBJECT_DIRECTORIES Colon-separated list (semicolon on Windows) with the same meaning, for one process.
git clone --reference <repo> Clone and add <repo> as an alternate, so already-known objects are not copied.
git clone --reference-if-able <repo> Same, but only warn if the reference does not exist.
git clone --dissociate After cloning, copy borrowed objects in and remove the alternate.
git clone --shared Use the source repository's objects directly, with no copy at all.
git repack -a -d Pull alternate objects into local packs. Add -l to leave them out instead.

Edge cases: alternates can chain, with a depth limit of 5. A missing directory only gives a warning at first, then errors when an object cannot be found.

Usage notes

  • Never delete or garbage-collect the donor carelessly. If the shared repository drops objects the borrower relies on (after gc --prune removes unreachable commits, or a rebased branch is force-pushed), the borrower becomes corrupt. Keep the donor append-only or run git repack -a -d in the borrower first.
  • Same machine or network filesystem. Alternates are plain paths, so they don't travel with git push or git clone of the borrower.
  • Savings. Big wins for many clones of one project; negligible for a single clone.
  • git gc in the borrower will not touch the donor's objects. Use git count-objects -v to see how much is local.
  • Security. An alternates file can point anywhere that Git can read. Do not accept repositories or .git tarballs from strangers, because the file lets them make Git read paths of their choosing.
  • Alternate refs. core.alternateRefsCommand and core.alternateRefsPrefixes make a server advertise the donors' tips, so pushes avoid sending objects the donor already has.
  • Alternatives: partial clone (--filter=blob:none) and git worktree save space without a shared store.