{ "mode": "man", "parameter": "gitrepository-layout", "section": "5", "url": "https://www.chedong.com/phpMan.php/man/gitrepository-layout/5/json", "generated": "2026-07-05T11:43:43Z", "synopsis": "$GITDIR/*", "sections": { "NAME": { "content": "gitrepository-layout - Git Repository Layout\n", "subsections": [] }, "SYNOPSIS": { "content": "$GITDIR/*\n", "subsections": [] }, "DESCRIPTION": { "content": "A Git repository comes in two different flavours:\n\n• a .git directory at the root of the working tree;\n\n• a .git directory that is a bare repository (i.e. without its own working tree),\nthat is typically used for exchanging histories with others by pushing into it and\nfetching from it.\n\nNote: Also you can have a plain text file .git at the root of your working tree, containing\ngitdir: to point at the real directory that has the repository. This mechanism is\noften used for a working tree of a submodule checkout, to allow you in the containing\nsuperproject to git checkout a branch that does not have the submodule. The checkout has to\nremove the entire submodule working tree, without losing the submodule repository.\n\nThese things may exist in a Git repository.\n\nobjects\nObject store associated with this repository. Usually an object store is self sufficient\n(i.e. all the objects that are referred to by an object found in it are also found in\nit), but there are a few ways to violate it.\n\n1. You could have an incomplete but locally usable repository by creating a shallow\nclone. See git-clone(1).\n\n2. You could be using the objects/info/alternates or $GITALTERNATEOBJECTDIRECTORIES\nmechanisms to borrow objects from other object stores. A repository with this kind of\nincomplete object store is not suitable to be published for use with dumb transports\nbut otherwise is OK as long as objects/info/alternates points at the object stores it\nborrows from.\n\nThis directory is ignored if $GITCOMMONDIR is set and \"$GITCOMMONDIR/objects\"\nwill be used instead.\n\nobjects/[0-9a-f][0-9a-f]\nA newly created object is stored in its own file. The objects are splayed over 256\nsubdirectories using the first two characters of the sha1 object name to keep the number\nof directory entries in objects itself to a manageable number. Objects found here are\noften called unpacked (or loose) objects.\n\nobjects/pack\nPacks (files that store many objects in compressed form, along with index files to allow\nthem to be randomly accessed) are found in this directory.\n\nobjects/info\nAdditional information about the object store is recorded in this directory.\n\nobjects/info/packs\nThis file is to help dumb transports discover what packs are available in this object\nstore. Whenever a pack is added or removed, git update-server-info should be run to keep\nthis file up to date if the repository is published for dumb transports. git repack does\nthis by default.\n\nobjects/info/alternates\nThis file records paths to alternate object stores that this object store borrows objects\nfrom, one pathname per line. Note that not only native Git tools use it locally, but the\nHTTP fetcher also tries to use it remotely; this will usually work if you have relative\npaths (relative to the object database, not to the repository!) in your alternates file,\nbut it will not work if you use absolute paths unless the absolute path in filesystem and\nweb URL is the same. See also objects/info/http-alternates.\n\nobjects/info/http-alternates\nThis file records URLs to alternate object stores that this object store borrows objects\nfrom, to be used when the repository is fetched over HTTP.\n\nrefs\nReferences are stored in subdirectories of this directory. The git prune command knows to\npreserve objects reachable from refs found in this directory and its subdirectories. This\ndirectory is ignored (except refs/bisect, refs/rewritten and refs/worktree) if\n$GITCOMMONDIR is set and \"$GITCOMMONDIR/refs\" will be used instead.\n\nrefs/heads/name\nrecords tip-of-the-tree commit objects of branch name\n\nrefs/tags/name\nrecords any object name (not necessarily a commit object, or a tag object that points at\na commit object).\n\nrefs/remotes/name\nrecords tip-of-the-tree commit objects of branches copied from a remote repository.\n\nrefs/replace/\nrecords the SHA-1 of the object that replaces . This is similar to info/grafts\nand is internally used and maintained by git-replace(1). Such refs can be exchanged\nbetween repositories while grafts are not.\n\npacked-refs\nrecords the same information as refs/heads/, refs/tags/, and friends record in a more\nefficient way. See git-pack-refs(1). This file is ignored if $GITCOMMONDIR is set and\n\"$GITCOMMONDIR/packed-refs\" will be used instead.\n\nHEAD\nA symref (see glossary) to the refs/heads/ namespace describing the currently active\nbranch. It does not mean much if the repository is not associated with any working tree\n(i.e. a bare repository), but a valid Git repository must have the HEAD file; some\nporcelains may use it to guess the designated \"default\" branch of the repository (usually\nmaster). It is legal if the named branch name does not (yet) exist. In some legacy\nsetups, it is a symbolic link instead of a symref that points at the current branch.\n\nHEAD can also record a specific commit directly, instead of being a symref to point at\nthe current branch. Such a state is often called detached HEAD. See git-checkout(1) for\ndetails.\n\nconfig\nRepository specific configuration file. This file is ignored if $GITCOMMONDIR is set\nand \"$GITCOMMONDIR/config\" will be used instead.\n\nconfig.worktree\nWorking directory specific configuration file for the main working directory in multiple\nworking directory setup (see git-worktree(1)).\n\nbranches\nA slightly deprecated way to store shorthands to be used to specify a URL to git fetch,\ngit pull and git push. A file can be stored as branches/ and then name can be given\nto these commands in place of repository argument. See the REMOTES section in git-\nfetch(1) for details. This mechanism is legacy and not likely to be found in modern\nrepositories. This directory is ignored if $GITCOMMONDIR is set and\n\"$GITCOMMONDIR/branches\" will be used instead.\n\nhooks\nHooks are customization scripts used by various Git commands. A handful of sample hooks\nare installed when git init is run, but all of them are disabled by default. To enable,\nthe .sample suffix has to be removed from the filename by renaming. Read githooks(5) for\nmore details about each hook. This directory is ignored if $GITCOMMONDIR is set and\n\"$GITCOMMONDIR/hooks\" will be used instead.\n\ncommon\nWhen multiple working trees are used, most of files in $GITDIR are per-worktree with a\nfew known exceptions. All files under common however will be shared between all working\ntrees.\n\nindex\nThe current index file for the repository. It is usually not found in a bare repository.\n\nsharedindex.\nThe shared index part, to be referenced by $GITDIR/index and other temporary index\nfiles. Only valid in split index mode.\n\ninfo\nAdditional information about the repository is recorded in this directory. This directory\nis ignored if $GITCOMMONDIR is set and \"$GITCOMMONDIR/info\" will be used instead.\n\ninfo/refs\nThis file helps dumb transports discover what refs are available in this repository. If\nthe repository is published for dumb transports, this file should be regenerated by git\nupdate-server-info every time a tag or branch is created or modified. This is normally\ndone from the hooks/update hook, which is run by the git-receive-pack command when you\ngit push into the repository.\n\ninfo/grafts\nThis file records fake commit ancestry information, to pretend the set of parents a\ncommit has is different from how the commit was actually created. One record per line\ndescribes a commit and its fake parents by listing their 40-byte hexadecimal object names\nseparated by a space and terminated by a newline.\n\nNote that the grafts mechanism is outdated and can lead to problems transferring objects\nbetween repositories; see git-replace(1) for a more flexible and robust system to do the\nsame thing.\n\ninfo/exclude\nThis file, by convention among Porcelains, stores the exclude pattern list. .gitignore\nis the per-directory ignore file. git status, git add, git rm and git clean look at it\nbut the core Git commands do not look at it. See also: gitignore(5).\n\ninfo/attributes\nDefines which attributes to assign to a path, similar to per-directory .gitattributes\nfiles. See also: gitattributes(5).\n\ninfo/sparse-checkout\nThis file stores sparse checkout patterns. See also: git-read-tree(1).\n\nremotes\nStores shorthands for URL and default refnames for use when interacting with remote\nrepositories via git fetch, git pull and git push commands. See the REMOTES section in\ngit-fetch(1) for details. This mechanism is legacy and not likely to be found in modern\nrepositories. This directory is ignored if $GITCOMMONDIR is set and\n\"$GITCOMMONDIR/remotes\" will be used instead.\n\nlogs\nRecords of changes made to refs are stored in this directory. See git-update-ref(1) for\nmore information. This directory is ignored (except logs/HEAD) if $GITCOMMONDIR is set\nand \"$GITCOMMONDIR/logs\" will be used instead.\n\nlogs/refs/heads/name\nRecords all changes made to the branch tip named name.\n\nlogs/refs/tags/name\nRecords all changes made to the tag named name.\n\nshallow\nThis is similar to info/grafts but is internally used and maintained by shallow clone\nmechanism. See --depth option to git-clone(1) and git-fetch(1). This file is ignored if\n$GITCOMMONDIR is set and \"$GITCOMMONDIR/shallow\" will be used instead.\n\ncommondir\nIf this file exists, $GITCOMMONDIR (see git(1)) will be set to the path specified in\nthis file if it is not explicitly set. If the specified path is relative, it is relative\nto $GITDIR. The repository with commondir is incomplete without the repository pointed\nby \"commondir\".\n\nmodules\nContains the git-repositories of the submodules.\n\nworktrees\nContains administrative data for linked working trees. Each subdirectory contains the\nworking tree-related part of a linked working tree. This directory is ignored if\n$GITCOMMONDIR is set, in which case \"$GITCOMMONDIR/worktrees\" will be used instead.\n\nworktrees//gitdir\nA text file containing the absolute path back to the .git file that points to here. This\nis used to check if the linked repository has been manually removed and there is no need\nto keep this directory any more. The mtime of this file should be updated every time the\nlinked repository is accessed.\n\nworktrees//locked\nIf this file exists, the linked working tree may be on a portable device and not\navailable. The presence of this file prevents worktrees/ from being pruned either\nautomatically or manually by git worktree prune. The file may contain a string explaining\nwhy the repository is locked.\n\nworktrees//config.worktree\nWorking directory specific configuration file.\n", "subsections": [] }, "GIT REPOSITORY FORMAT VERSIONS": { "content": "Every git repository is marked with a numeric version in the core.repositoryformatversion key\nof its config file. This version specifies the rules for operating on the on-disk repository\ndata. An implementation of git which does not understand a particular version advertised by\nan on-disk repository MUST NOT operate on that repository; doing so risks not only producing\nwrong results, but actually losing data.\n\nBecause of this rule, version bumps should be kept to an absolute minimum. Instead, we\ngenerally prefer these strategies:\n\n• bumping format version numbers of individual data files (e.g., index, packfiles, etc).\nThis restricts the incompatibilities only to those files.\n\n• introducing new data that gracefully degrades when used by older clients (e.g., pack\nbitmap files are ignored by older clients, which simply do not take advantage of the\noptimization they provide).\n\nA whole-repository format version bump should only be part of a change that cannot be\nindependently versioned. For instance, if one were to change the reachability rules for\nobjects, or the rules for locking refs, that would require a bump of the repository format\nversion.\n\nNote that this applies only to accessing the repository’s disk contents directly. An older\nclient which understands only format 0 may still connect via git:// to a repository using\nformat 1, as long as the server process understands format 1.\n\nThe preferred strategy for rolling out a version bump (whether whole repository or for a\nsingle file) is to teach git to read the new format, and allow writing the new format with a\nconfig switch or command line option (for experimentation or for those who do not care about\nbackwards compatibility with older gits). Then after a long period to allow the reading\ncapability to become common, we may switch to writing the new format by default.\n\nThe currently defined format versions are:\n", "subsections": [ { "name": "Version 0", "content": "This is the format defined by the initial version of git, including but not limited to the\nformat of the repository directory, the repository configuration file, and the object and ref\nstorage. Specifying the complete behavior of git is beyond the scope of this document.\n" }, { "name": "Version 1", "content": "This format is identical to version 0, with the following exceptions:\n\n1. When reading the core.repositoryformatversion variable, a git implementation which\nsupports version 1 MUST also read any configuration keys found in the extensions section\nof the configuration file.\n\n2. If a version-1 repository specifies any extensions.* keys that the running git has not\nimplemented, the operation MUST NOT proceed. Similarly, if the value of any known key is\nnot understood by the implementation, the operation MUST NOT proceed.\n\nNote that if no extensions are specified in the config file, then\ncore.repositoryformatversion SHOULD be set to 0 (setting it to 1 provides no benefit, and\nmakes the repository incompatible with older implementations of git).\n\nThis document will serve as the master list for extensions. Any implementation wishing to\ndefine a new extension should make a note of it here, in order to claim the name.\n\nThe defined extensions are:\n" }, { "name": "noop", "content": "This extension does not change git’s behavior at all. It is useful only for testing\nformat-1 compatibility.\n" }, { "name": "preciousObjects", "content": "When the config key extensions.preciousObjects is set to true, objects in the repository\nMUST NOT be deleted (e.g., by git-prune or git repack -d).\n" }, { "name": "partialclone", "content": "When the config key extensions.partialclone is set, it indicates that the repo was\ncreated with a partial clone (or later performed a partial fetch) and that the remote may\nhave omitted sending certain unwanted objects. Such a remote is called a \"promisor\nremote\" and it promises that all such omitted objects can be fetched from it in the\nfuture.\n\nThe value of this key is the name of the promisor remote.\n" }, { "name": "worktreeConfig", "content": "If set, by default \"git config\" reads from both \"config\" and \"config.worktree\" file from\nGITDIR in that order. In multiple working directory mode, \"config\" file is shared while\n\"config.worktree\" is per-working directory (i.e., it’s in\nGITCOMMONDIR/worktrees//config.worktree)\n" } ] }, "SEE ALSO": { "content": "git-init(1), git-clone(1), git-fetch(1), git-pack-refs(1), git-gc(1), git-checkout(1),\ngitglossary(7), The Git User’’s Manual[1]\n", "subsections": [] }, "GIT": { "content": "Part of the git(1) suite\n", "subsections": [] }, "NOTES": { "content": "1. The Git User’s Manual\nfile:///usr/share/doc/git/html/user-manual.html\n\n\n\nGit 2.34.1 02/26/2026 GITREPOSITORY-LAYOU(5)", "subsections": [] } }, "summary": "gitrepository-layout - Git Repository Layout", "flags": [], "examples": [], "see_also": [ { "name": "git-init", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/git-init/1/json" }, { "name": "git-clone", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/git-clone/1/json" }, { "name": "git-fetch", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/git-fetch/1/json" }, { "name": "git-pack-refs", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/git-pack-refs/1/json" }, { "name": "git-gc", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/git-gc/1/json" }, { "name": "git-checkout", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/git-checkout/1/json" }, { "name": "gitglossary", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/gitglossary/7/json" } ] }