Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
GIT_OBJECT_DIRECTORY=/fast/objects git hash-object -w file.bin
GIT_ALTERNATE_OBJECT_DIRECTORIES=/srv/shared/objects git log

Try it

Bash Write an object into a different directory

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 Borrow objects with an alternate

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_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 HEAD stay 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 sets GIT_OBJECT_DIRECTORY to a temporary directory and the real store as an alternate, so pre-receive hooks can inspect incoming objects before they become permanent. A hook that spawns Git inherits those variables, which is why git rev-list in 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 --shared and --reference create this dependency; git repack -a -d makes 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_DIRECTORY helps 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.