Git Reference ยท Environment Variables
GIT_OBJECT_DIRECTORY
Reference for GIT_OBJECT_DIRECTORY and GIT_ALTERNATE_OBJECT_DIRECTORIES: store Git objects elsewhere, share them between repositories and read from extra object stores.
Every blob, tree, commit and tag lives in the repository's object database, normally .git/objects. GIT_OBJECT_DIRECTORY moves that location for a single command. Its partner GIT_ALTERNATE_OBJECT_DIRECTORIES adds extra, read-only places to look for objects that are not in the main store.
These variables are mostly used by tooling: quarantine areas during a push, forks that share one big object store, build servers that cache objects on fast disks, and tests that want an isolated store. For day-to-day sharing between repositories, the file objects/info/alternates is the persistent equivalent.
GIT_OBJECT_DIRECTORY=/fast/objects git hash-object -w file.bin
GIT_ALTERNATE_OBJECT_DIRECTORIES=/srv/shared/objects git log
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_OBJECT_DIRECTORY=<path> git <command> GIT_ALTERNATE_OBJECT_DIRECTORIES=<path>[:<path>...] git <command>
| Name | Description |
|---|---|
GIT_OBJECT_DIRECTORY |
Directory used instead of $GIT_DIR/objects for new objects and as the first place searched. |
GIT_ALTERNATE_OBJECT_DIRECTORIES |
Colon-separated (semicolon on Windows) list of extra object directories searched when an object is missing. Read-only: Git never writes there. |
Layout: each directory must have the usual structure, with loose objects in xx/yyyyโฆ folders and packfiles in pack/. Git creates the two-character subfolders on demand; create the top directory yourself first.
Edge cases: when an object is in none of the directories, commands fail with messages such as could not get object info or bad object. Alternates may themselves have an info/alternates file; Git follows such chains to a limited depth.
Usage notes
- Only the object store moves. Refs, the index and
HEADstay in$GIT_DIR. Pointing a repository at an object directory that lacks its commits leaves broken refs, so reach for this only for deliberate setups. - Push quarantine: during
receive-pack, Git setsGIT_OBJECT_DIRECTORYto a temporary directory and the real store as an alternate, sopre-receivehooks can inspect incoming objects before they become permanent. A hook that spawns Git inherits those variables, which is whygit rev-listin a hook can see pushed objects. - Sharing safely: a repository that borrows objects from another must never see the source pruned (
git gc --prune, deleting the folder), or its history breaks.git clone --sharedand--referencecreate this dependency;git repack -a -dmakes a repository independent again. - Garbage collection counts only the main store when deciding what to pack. Objects living in an alternate stay where they are.
- Performance: a fast local disk for
GIT_OBJECT_DIRECTORYhelps a CI runner with a slow checkout volume; alternates on network storage can make every command slower. - Hash format: the borrowed store must use the same object format (SHA-1 or SHA-256) as the repository.