gitrepository-layout - Git Repository Layout


          A Git repository comes in two different flavours:

          +o   a .git directory at the root of the working tree;

          +o   a <project>.git directory that is a bare repository
              (i.e. without its own working tree), that is typically
              used for exchanging histories with others by pushing
              into it and fetching from it.

          Note: Also you can have a plain text file .git at the root
          of your working tree, containing gitdir: <path> to point at
          the real directory that has the repository. This mechanism
          is often used for a working tree of a submodule checkout, to
          allow you in the containing superproject to git checkout a
          branch that does not have the submodule. The checkout has to
          remove the entire submodule working tree, without losing the
          submodule repository.

          These things may exist in a Git repository.

              Object store associated with this repository. Usually an
              object store is self sufficient (i.e. all the objects
              that are referred to by an object found in it are also
              found in it), but there are a few ways to violate it.

               1. You could have an incomplete but locally usable
                  repository by creating a shallow clone. See git-

               2. You could be using the objects/info/alternates or
                  $GIT_ALTERNATE_OBJECT_DIRECTORIES mechanisms to
                  borrow objects from other object stores. A
                  repository with this kind of incomplete object store
                  is not suitable to be published for use with dumb
                  transports but otherwise is OK as long as
                  objects/info/alternates points at the object stores
                  it borrows from.

                  This directory is ignored if $GIT_COMMON_DIR is set
                  and "$GIT_COMMON_DIR/objects" will be used instead.


     Page 1                     Git 2.33.0           (printed 5/26/22)


              A newly created object is stored in its own file. The
              objects are splayed over 256 subdirectories using the
              first two characters of the sha1 object name to keep the
              number of directory entries in objects itself to a
              manageable number. Objects found here are often called
              unpacked (or loose) objects.

              Packs (files that store many objects in compressed form,
              along with index files to allow them to be randomly
              accessed) are found in this directory.

              Additional information about the object store is
              recorded in this directory.

              This file is to help dumb transports discover what packs
              are available in this object store. Whenever a pack is
              added or removed, git update-server-info should be run
              to keep this file up to date if the repository is
              published for dumb transports.  git repack does this by

              This file records paths to alternate object stores that
              this object store borrows objects from, one pathname per
              line. Note that not only native Git tools use it
              locally, but the HTTP fetcher also tries to use it
              remotely; this will usually work if you have relative
              paths (relative to the object database, not to the
              repository!) in your alternates file, but it will not
              work if you use absolute paths unless the absolute path
              in filesystem and web URL is the same. See also

              This file records URLs to alternate object stores that
              this object store borrows objects from, to be used when
              the repository is fetched over HTTP.

              References are stored in subdirectories of this
              directory. The git prune command knows to preserve
              objects reachable from refs found in this directory and
              its subdirectories. This directory is ignored (except
              refs/bisect, refs/rewritten and refs/worktree) if
              $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/refs" will
              be used instead.

              records tip-of-the-tree commit objects of branch name

     Page 2                     Git 2.33.0           (printed 5/26/22)


              records any object name (not necessarily a commit
              object, or a tag object that points at a commit object).

              records tip-of-the-tree commit objects of branches
              copied from a remote repository.

              records the SHA-1 of the object that replaces
              <obj-sha1>. This is similar to info/grafts and is
              internally used and maintained by git-replace(1). Such
              refs can be exchanged between repositories while grafts
              are not.

              records the same information as refs/heads/, refs/tags/,
              and friends record in a more efficient way. See git-
              pack-refs(1). This file is ignored if $GIT_COMMON_DIR is
              set and "$GIT_COMMON_DIR/packed-refs" will be used

              A symref (see glossary) to the refs/heads/ namespace
              describing the currently active branch. It does not mean
              much if the repository is not associated with any
              working tree (i.e. a bare repository), but a valid Git
              repository must have the HEAD file; some porcelains may
              use it to guess the designated "default" branch of the
              repository (usually master). It is legal if the named
              branch name does not (yet) exist. In some legacy setups,
              it is a symbolic link instead of a symref that points at
              the current branch.

              HEAD can also record a specific commit directly, instead
              of being a symref to point at the current branch. Such a
              state is often called detached HEAD.  See git-
              checkout(1) for details.

              Repository specific configuration file. This file is
              ignored if $GIT_COMMON_DIR is set and
              "$GIT_COMMON_DIR/config" will be used instead.

              Working directory specific configuration file for the
              main working directory in multiple working directory
              setup (see git-worktree(1)).

              A slightly deprecated way to store shorthands to be used
              to specify a URL to git fetch, git pull and git push. A

     Page 3                     Git 2.33.0           (printed 5/26/22)


              file can be stored as branches/<name> and then name can
              be given to these commands in place of repository
              argument. See the REMOTES section in git-fetch(1) for
              details. This mechanism is legacy and not likely to be
              found in modern repositories. This directory is ignored
              if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/branches"
              will be used instead.

              Hooks are customization scripts used by various Git
              commands. A handful of sample hooks are installed when
              git init is run, but all of them are disabled by
              default. To enable, the .sample suffix has to be removed
              from the filename by renaming. Read githooks(5) for more
              details about each hook. This directory is ignored if
              $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/hooks" will
              be used instead.

              When multiple working trees are used, most of files in
              $GIT_DIR are per-worktree with a few known exceptions.
              All files under common however will be shared between
              all working trees.

              The current index file for the repository. It is usually
              not found in a bare repository.

              The shared index part, to be referenced by
              $GIT_DIR/index and other temporary index files. Only
              valid in split index mode.

              Additional information about the repository is recorded
              in this directory. This directory is ignored if
              $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/info" will
              be used instead.

              This file helps dumb transports discover what refs are
              available in this repository. If the repository is
              published for dumb transports, this file should be
              regenerated by git update-server-info every time a tag
              or branch is created or modified. This is normally done
              from the hooks/update hook, which is run by the
              git-receive-pack command when you git push into the

              This file records fake commit ancestry information, to
              pretend the set of parents a commit has is different

     Page 4                     Git 2.33.0           (printed 5/26/22)


              from how the commit was actually created. One record per
              line describes a commit and its fake parents by listing
              their 40-byte hexadecimal object names separated by a
              space and terminated by a newline.

              Note that the grafts mechanism is outdated and can lead
              to problems transferring objects between repositories;
              see git-replace(1) for a more flexible and robust system
              to do the same thing.

              This file, by convention among Porcelains, stores the
              exclude pattern list.  .gitignore is the per-directory
              ignore file.  git status, git add, git rm and git clean
              look at it but the core Git commands do not look at it.
              See also: gitignore(5).

              Defines which attributes to assign to a path, similar to
              per-directory .gitattributes files. See also:

              This file stores sparse checkout patterns. See also:

              Stores shorthands for URL and default refnames for use
              when interacting with remote repositories via git fetch,
              git pull and git push commands. See the REMOTES section
              in git-fetch(1) for details. This mechanism is legacy
              and not likely to be found in modern repositories. This
              directory is ignored if $GIT_COMMON_DIR is set and
              "$GIT_COMMON_DIR/remotes" will be used instead.

              Records of changes made to refs are stored in this
              directory. See git-update-ref(1) for more information.
              This directory is ignored (except logs/HEAD) if
              $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/logs" will
              be used instead.

              Records all changes made to the branch tip named name.

              Records all changes made to the tag named name.

              This is similar to info/grafts but is internally used
              and maintained by shallow clone mechanism. See --depth
              option to git-clone(1) and git-fetch(1). This file is

     Page 5                     Git 2.33.0           (printed 5/26/22)


              ignored if $GIT_COMMON_DIR is set and
              "$GIT_COMMON_DIR/shallow" will be used instead.

              If this file exists, $GIT_COMMON_DIR (see git(1)) will
              be set to the path specified in this file if it is not
              explicitly set. If the specified path is relative, it is
              relative to $GIT_DIR. The repository with commondir is
              incomplete without the repository pointed by

              Contains the git-repositories of the submodules.

              Contains administrative data for linked working trees.
              Each subdirectory contains the working tree-related part
              of a linked working tree. This directory is ignored if
              $GIT_COMMON_DIR is set, in which case
              "$GIT_COMMON_DIR/worktrees" will be used instead.

              A text file containing the absolute path back to the
              .git file that points to here. This is used to check if
              the linked repository has been manually removed and
              there is no need to keep this directory any more. The
              mtime of this file should be updated every time the
              linked repository is accessed.

              If this file exists, the linked working tree may be on a
              portable device and not available. The presence of this
              file prevents worktrees/<id> from being pruned either
              automatically or manually by git worktree prune. The
              file may contain a string explaining why the repository
              is locked.

              Working directory specific configuration file.

          Every git repository is marked with a numeric version in the
          core.repositoryformatversion key of its config file. This
          version specifies the rules for operating on the on-disk
          repository data. An implementation of git which does not
          understand a particular version advertised by an on-disk
          repository MUST NOT operate on that repository; doing so
          risks not only producing wrong results, but actually losing

          Because of this rule, version bumps should be kept to an
          absolute minimum. Instead, we generally prefer these

     Page 6                     Git 2.33.0           (printed 5/26/22)



          +o   bumping format version numbers of individual data files
              (e.g., index, packfiles, etc). This restricts the
              incompatibilities only to those files.

          +o   introducing new data that gracefully degrades when used
              by older clients (e.g., pack bitmap files are ignored by
              older clients, which simply do not take advantage of the
              optimization they provide).

          A whole-repository format version bump should only be part
          of a change that cannot be independently versioned. For
          instance, if one were to change the reachability rules for
          objects, or the rules for locking refs, that would require a
          bump of the repository format version.

          Note that this applies only to accessing the repositorycqs
          disk contents directly. An older client which understands
          only format 0 may still connect via git:// to a repository
          using format 1, as long as the server process understands
          format 1.

          The preferred strategy for rolling out a version bump
          (whether whole repository or for a single file) is to teach
          git to read the new format, and allow writing the new format
          with a config switch or command line option (for
          experimentation or for those who do not care about backwards
          compatibility with older gits). Then after a long period to
          allow the reading capability to become common, we may switch
          to writing the new format by default.

          The currently defined format versions are:

        Version 0
          This is the format defined by the initial version of git,
          including but not limited to the format of the repository
          directory, the repository configuration file, and the object
          and ref storage. Specifying the complete behavior of git is
          beyond the scope of this document.

        Version 1
          This format is identical to version 0, with the following

           1. When reading the core.repositoryformatversion variable,
              a git implementation which supports version 1 MUST also
              read any configuration keys found in the extensions
              section of the configuration file.

           2. If a version-1 repository specifies any extensions.*
              keys that the running git has not implemented, the

     Page 7                     Git 2.33.0           (printed 5/26/22)


              operation MUST NOT proceed. Similarly, if the value of
              any known key is not understood by the implementation,
              the operation MUST NOT proceed.

          Note that if no extensions are specified in the config file,
          then core.repositoryformatversion SHOULD be set to 0
          (setting it to 1 provides no benefit, and makes the
          repository incompatible with older implementations of git).

          This document will serve as the master list for extensions.
          Any implementation wishing to define a new extension should
          make a note of it here, in order to claim the name.

          The defined extensions are:


              This extension does not change gitcqs behavior at all. It
              is useful only for testing format-1 compatibility.


              When the config key extensions.preciousObjects is set to
              true, objects in the repository MUST NOT be deleted
              (e.g., by git-prune or git repack -d).


              When the config key extensions.partialclone is set, it
              indicates that the repo was created with a partial clone
              (or later performed a partial fetch) and that the remote
              may have omitted sending certain unwanted objects. Such
              a remote is called a "promisor remote" and it promises
              that all such omitted objects can be fetched from it in
              the future.

              The value of this key is the name of the promisor


              If set, by default "git config" reads from both "config"
              and "config.worktree" file from GIT_DIR in that order.
              In multiple working directory mode, "config" file is
              shared while "config.worktree" is per-working directory
              (i.e., itcqs in

          git-init(1), git-clone(1), git-fetch(1), git-pack-refs(1),
          git-gc(1), git-checkout(1), gitglossary(7), m[blue]The Git
          Usercqs Manualm[][1]

     Page 8                     Git 2.33.0           (printed 5/26/22)


          Part of the git(1) suite

           1. The Git Usercqs Manual

     Page 9                     Git 2.33.0           (printed 5/26/22)