Documentation/gitrepository-layout.txt

   1 gitrepository-layout(5)
   2 =======================
   3
   4 NAME
   5 ----
   6 gitrepository-layout - Git Repository Layout
   7
   8 SYNOPSIS
   9 --------
  10 $GIT_DIR/*
  11
  12 DESCRIPTION
  13 -----------
  14
  15 You may find these things in your git repository (`.git`
  16 directory for a repository associated with your working tree, or
  17 `<project>.git` directory for a public 'bare' repository. It is
  18 also possible to have a working tree where `.git` is a plain
  19 ASCII file containing `gitdir: <path>`, i.e. the path to the
  20 real git repository).
  21
  22 objects::
  23         Object store associated with this repository.  Usually
  24         an object store is self sufficient (i.e. all the objects
  25         that are referred to by an object found in it are also
  26         found in it), but there are a few ways to violate it.
  27 +
  28 . You could have an incomplete but locally usable repository
  29 by creating a shallow clone.  See linkgit:git-clone[1].
  30 . You could be using the `objects/info/alternates` or
  31 `$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow'
  32 objects from other object stores.  A repository with this kind
  33 of incomplete object store is not suitable to be published for
  34 use with dumb transports but otherwise is OK as long as
  35 `objects/info/alternates` points at the object stores it
  36 borrows from.
  37
  38 objects/[0-9a-f][0-9a-f]::
  39         A newly created object is stored in its own file.
  40         The objects are splayed over 256 subdirectories using
  41         the first two characters of the sha1 object name to
  42         keep the number of directory entries in `objects`
  43         itself to a manageable number. Objects found
  44         here are often called 'unpacked' (or 'loose') objects.
  45
  46 objects/pack::
  47         Packs (files that store many object in compressed form,
  48         along with index files to allow them to be randomly
  49         accessed) are found in this directory.
  50
  51 objects/info::
  52         Additional information about the object store is
  53         recorded in this directory.
  54
  55 objects/info/packs::
  56         This file is to help dumb transports discover what packs
  57         are available in this object store.  Whenever a pack is
  58         added or removed, `git update-server-info` should be run
  59         to keep this file up-to-date if the repository is
  60         published for dumb transports.  'git repack' does this
  61         by default.
  62
  63 objects/info/alternates::
  64         This file records paths to alternate object stores that
  65         this object store borrows objects from, one pathname per
  66         line. Note that not only native Git tools use it locally,
  67         but the HTTP fetcher also tries to use it remotely; this
  68         will usually work if you have relative paths (relative
  69         to the object database, not to the repository!) in your
  70         alternates file, but it will not work if you use absolute
  71         paths unless the absolute path in filesystem and web URL
  72         is the same. See also 'objects/info/http-alternates'.
  73
  74 objects/info/http-alternates::
  75         This file records URLs to alternate object stores that
  76         this object store borrows objects from, to be used when
  77         the repository is fetched over HTTP.
  78
  79 refs::
  80         References are stored in subdirectories of this
  81         directory.  The 'git prune' command knows to preserve
  82         objects reachable from refs found in this directory and
  83         its subdirectories.
  84
  85 refs/heads/`name`::
  86         records tip-of-the-tree commit objects of branch `name`
  87
  88 refs/tags/`name`::
  89         records any object name (not necessarily a commit
  90         object, or a tag object that points at a commit object).
  91
  92 refs/remotes/`name`::
  93         records tip-of-the-tree commit objects of branches copied
  94         from a remote repository.
  95
  96 refs/replace/`<obj-sha1>`::
  97         records the SHA1 of the object that replaces `<obj-sha1>`.
  98         This is similar to info/grafts and is internally used and
  99         maintained by linkgit:git-replace[1]. Such refs can be exchanged
 100         between repositories while grafts are not.
 101
 102 packed-refs::
 103         records the same information as refs/heads/, refs/tags/,
 104         and friends record in a more efficient way.  See
 105         linkgit:git-pack-refs[1].
 106
 107 HEAD::
 108         A symref (see glossary) to the `refs/heads/` namespace
 109         describing the currently active branch.  It does not mean
 110         much if the repository is not associated with any working tree
 111         (i.e. a 'bare' repository), but a valid git repository
 112         *must* have the HEAD file; some porcelains may use it to
 113         guess the designated "default" branch of the repository
 114         (usually 'master').  It is legal if the named branch
 115         'name' does not (yet) exist.  In some legacy setups, it is
 116         a symbolic link instead of a symref that points at the current
 117         branch.
 118 +
 119 HEAD can also record a specific commit directly, instead of
 120 being a symref to point at the current branch.  Such a state
 121 is often called 'detached HEAD.'  See linkgit:git-checkout[1]
 122 for details.
 123
 124 branches::
 125         A slightly deprecated way to store shorthands to be used
 126         to specify a URL to 'git fetch', 'git pull' and 'git push'.
 127         A file can be stored as `branches/<name>` and then
 128         'name' can be given to these commands in place of
 129         'repository' argument.  See the REMOTES section in
 130         linkgit:git-fetch[1] for details.  This mechanism is legacy
 131         and not likely to be found in modern repositories.
 132
 133 hooks::
 134         Hooks are customization scripts used by various git
 135         commands.  A handful of sample hooks are installed when
 136         'git init' is run, but all of them are disabled by
 137         default.  To enable, the `.sample` suffix has to be
 138         removed from the filename by renaming.
 139         Read linkgit:githooks[5] for more details about
 140         each hook.
 141
 142 index::
 143         The current index file for the repository.  It is
 144         usually not found in a bare repository.
 145
 146 info::
 147         Additional information about the repository is recorded
 148         in this directory.
 149
 150 info/refs::
 151         This file helps dumb transports discover what refs are
 152         available in this repository.  If the repository is
 153         published for dumb transports, this file should be
 154         regenerated by 'git update-server-info' every time a tag
 155         or branch is created or modified.  This is normally done
 156         from the `hooks/update` hook, which is run by the
 157         'git-receive-pack' command when you 'git push' into the
 158         repository.
 159
 160 info/grafts::
 161         This file records fake commit ancestry information, to
 162         pretend the set of parents a commit has is different
 163         from how the commit was actually created.  One record
 164         per line describes a commit and its fake parents by
 165         listing their 40-byte hexadecimal object names separated
 166         by a space and terminated by a newline.
 167
 168 info/exclude::
 169         This file, by convention among Porcelains, stores the
 170         exclude pattern list. `.gitignore` is the per-directory
 171         ignore file.  'git status', 'git add', 'git rm' and
 172         'git clean' look at it but the core git commands do not look
 173         at it.  See also: linkgit:gitignore[5].
 174
 175 remotes::
 176         Stores shorthands for URL and default refnames for use
 177         when interacting with remote repositories via 'git fetch',
 178         'git pull' and 'git push' commands.  See the REMOTES section
 179         in linkgit:git-fetch[1] for details.  This mechanism is legacy
 180         and not likely to be found in modern repositories.
 181
 182 logs::
 183         Records of changes made to refs are stored in this
 184         directory.  See linkgit:git-update-ref[1]
 185         for more information.
 186
 187 logs/refs/heads/`name`::
 188         Records all changes made to the branch tip named `name`.
 189
 190 logs/refs/tags/`name`::
 191         Records all changes made to the tag named `name`.
 192
 193 shallow::
 194         This is similar to `info/grafts` but is internally used
 195         and maintained by shallow clone mechanism.  See `--depth`
 196         option to linkgit:git-clone[1] and linkgit:git-fetch[1].
 197
 198 SEE ALSO
 199 --------
 200 linkgit:git-init[1],
 201 linkgit:git-clone[1],
 202 linkgit:git-fetch[1],
 203 linkgit:git-pack-refs[1],
 204 linkgit:git-gc[1],
 205 linkgit:git-checkout[1],
 206 linkgit:gitglossary[7],
 207 link:user-manual.html[The Git User's Manual]
 208
 209 GIT
 210 ---
 211 Part of the linkgit:git[1] suite.