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 packed-refs::
  97         records the same information as refs/heads/, refs/tags/,
  98         and friends record in a more efficient way.  See
  99         linkgit:git-pack-refs[1].
 100
 101 HEAD::
 102         A symref (see glossary) to the `refs/heads/` namespace
 103         describing the currently active branch.  It does not mean
 104         much if the repository is not associated with any working tree
 105         (i.e. a 'bare' repository), but a valid git repository
 106         *must* have the HEAD file; some porcelains may use it to
 107         guess the designated "default" branch of the repository
 108         (usually 'master').  It is legal if the named branch
 109         'name' does not (yet) exist.  In some legacy setups, it is
 110         a symbolic link instead of a symref that points at the current
 111         branch.
 112 +
 113 HEAD can also record a specific commit directly, instead of
 114 being a symref to point at the current branch.  Such a state
 115 is often called 'detached HEAD.'  See linkgit:git-checkout[1]
 116 for details.
 117
 118 branches::
 119         A slightly deprecated way to store shorthands to be used
 120         to specify a URL to 'git fetch', 'git pull' and 'git push'.
 121         A file can be stored as `branches/<name>` and then
 122         'name' can be given to these commands in place of
 123         'repository' argument.  See the REMOTES section in
 124         linkgit:git-fetch[1] for details.  This mechanism is legacy
 125         and not likely to be found in modern repositories.
 126
 127 hooks::
 128         Hooks are customization scripts used by various git
 129         commands.  A handful of sample hooks are installed when
 130         'git init' is run, but all of them are disabled by
 131         default.  To enable, the `.sample` suffix has to be
 132         removed from the filename by renaming.
 133         Read linkgit:githooks[5] for more details about
 134         each hook.
 135
 136 index::
 137         The current index file for the repository.  It is
 138         usually not found in a bare repository.
 139
 140 info::
 141         Additional information about the repository is recorded
 142         in this directory.
 143
 144 info/refs::
 145         This file helps dumb transports discover what refs are
 146         available in this repository.  If the repository is
 147         published for dumb transports, this file should be
 148         regenerated by 'git update-server-info' every time a tag
 149         or branch is created or modified.  This is normally done
 150         from the `hooks/update` hook, which is run by the
 151         'git-receive-pack' command when you 'git push' into the
 152         repository.
 153
 154 info/grafts::
 155         This file records fake commit ancestry information, to
 156         pretend the set of parents a commit has is different
 157         from how the commit was actually created.  One record
 158         per line describes a commit and its fake parents by
 159         listing their 40-byte hexadecimal object names separated
 160         by a space and terminated by a newline.
 161
 162 info/exclude::
 163         This file, by convention among Porcelains, stores the
 164         exclude pattern list. `.gitignore` is the per-directory
 165         ignore file.  'git status', 'git add', 'git rm' and
 166         'git clean' look at it but the core git commands do not look
 167         at it.  See also: linkgit:gitignore[5].
 168
 169 remotes::
 170         Stores shorthands for URL and default refnames for use
 171         when interacting with remote repositories via 'git fetch',
 172         'git pull' and 'git push' commands.  See the REMOTES section
 173         in linkgit:git-fetch[1] for details.  This mechanism is legacy
 174         and not likely to be found in modern repositories.
 175
 176 logs::
 177         Records of changes made to refs are stored in this
 178         directory.  See linkgit:git-update-ref[1]
 179         for more information.
 180
 181 logs/refs/heads/`name`::
 182         Records all changes made to the branch tip named `name`.
 183
 184 logs/refs/tags/`name`::
 185         Records all changes made to the tag named `name`.
 186
 187 shallow::
 188         This is similar to `info/grafts` but is internally used
 189         and maintained by shallow clone mechanism.  See `--depth`
 190         option to linkgit:git-clone[1] and linkgit:git-fetch[1].
 191
 192 SEE ALSO
 193 --------
 194 linkgit:git-init[1],
 195 linkgit:git-clone[1],
 196 linkgit:git-fetch[1],
 197 linkgit:git-pack-refs[1],
 198 linkgit:git-gc[1],
 199 linkgit:git-checkout[1],
 200 linkgit:gitglossary[7],
 201 link:user-manual.html[The Git User's Manual]
 202
 203 GIT
 204 ---
 205 Part of the linkgit:git[1] suite.