What is the Git "alternates mechanism"?

Question

I'm studying through man gitglossary, and this one term has eluded me—because it isn't defined in the glossary at all.

It's referred to only twice (asterisks added):

   alternate object database
       Via the **alternates mechanism**, a repository can inherit part of its
       object database from another object database, which is called
       "alternate".

   repository
       A collection of refs together with an object database containing
       all objects which are reachable from the refs, possibly accompanied
       by meta data from one or more porcelains. A repository can share an
       object database with other repositories via **alternates mechanism**.

What is the "alternates mechanism" that is referred to here?

Answer 1

The short answer is that you can point any existing git repository to any number of additional existing git repositories—specifically, to their .git/objects directories—after which your git will search for objects in both your own .git/objects directory and all the other listed ones (in listing order).

What's tougher to describe is why you might want to do this.

It helps if you know how git works internally. In git, identifiers tend to resolve fairly quickly to their hash ID:

$ git rev-parse master
3266f25e27f69edbfc513a3b3cfd3987a89beff2

Git then looks for the object corresponding to this ID. In this case, the object is a commit. If your goal is to do something with the commit—such as check it out, or diff it against some other commit—git reads the object, which contains the ID of a tree. Git then reads the tree object; this contains the names of additional trees and files ("blobs"), and their IDs, and git reads those objects to find the files and, recursively, the sub-trees and their files.

Now suppose that you have an existing copy of a very large repository, and—for whatever reason—you want to clone it again (perhaps to have a separate clone for working in a separate branch).¹ Rather than making a second complete copy of the original repository, you can tell git that all the original objects are available in the first repository. Once git has the alternates entry, it will be able to find those objects and will not need to download them.

New objects you create in this second clone will, of course, just go in the second clone; but this saves a lot of time and space.

("Shared" clones on a single machine generally link directly to the other clone's objects, using Unix-style hard links, but if this is not possible, the alternates mechanism provides another way to do the same thing. The danger with alternates is that if the first clone is removed, the objects go away; hard links don't have this flaw. A --reference clone also uses the alternates mechanism.)

As for:

Where is the official documentation that defines it?

the best answer is probably "in the source". :-)

---

¹Now that git has the ability to provide multiple work trees from a single clone, this is less important than it once was.