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.
echo /srv/mirror/linux.git/objects >> .git/objects/info/alternates
Try 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.
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
# .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 --pruneremoves unreachable commits, or a rebased branch is force-pushed), the borrower becomes corrupt. Keep the donor append-only or rungit repack -a -din the borrower first. - Same machine or network filesystem. Alternates are plain paths, so they don't travel with
git pushorgit cloneof the borrower. - Savings. Big wins for many clones of one project; negligible for a single clone.
git gcin the borrower will not touch the donor's objects. Usegit count-objects -vto see how much is local.- Security. An alternates file can point anywhere that Git can read. Do not accept repositories or
.gittarballs from strangers, because the file lets them make Git read paths of their choosing. - Alternate refs.
core.alternateRefsCommandandcore.alternateRefsPrefixesmake a server advertise the donors' tips, so pushes avoid sending objects the donor already has. - Alternatives: partial clone (
--filter=blob:none) andgit worktreesave space without a shared store.