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 couple of ways to violate
  27         it.
  28 +
  29 . You could populate the repository by running a commit walker
  30 without `-a` option.  Depending on which options are given, you
  31 could have only commit objects without associated blobs and
  32 trees this way, for example.  A repository with this kind of
  33 incomplete object store is not suitable to be published to the
  34 outside world but sometimes useful for private repository.
  35 . You also could have an incomplete but locally usable repository
  36 by cloning shallowly.  See linkgit:git-clone[1].
  37 . You can be using `objects/info/alternates` mechanism, or
  38 `$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'
  39 objects from other object stores.  A repository with this kind
  40 of incomplete object store is not suitable to be published for
  41 use with dumb transports but otherwise is OK as long as
  42 `objects/info/alternates` points at the right object stores
  43 it borrows from.
  44
  45 objects/[0-9a-f][0-9a-f]::
  46         Traditionally, each object is stored in its own file.
  47         They are split into 256 subdirectories using the first
  48         two letters from its object name to keep the number of
  49         directory entries `objects` directory itself needs to
  50         hold.  Objects found here are often called 'unpacked'
  51         (or 'loose') objects.
  52
  53 objects/pack::
  54         Packs (files that store many object in compressed form,
  55         along with index files to allow them to be randomly
  56         accessed) are found in this directory.
  57
  58 objects/info::
  59         Additional information about the object store is
  60         recorded in this directory.
  61
  62 objects/info/packs::
  63         This file is to help dumb transports discover what packs
  64         are available in this object store.  Whenever a pack is
  65         added or removed, `git update-server-info` should be run
  66         to keep this file up-to-date if the repository is
  67         published for dumb transports.  `git repack` does this
  68         by default.
  69
  70 objects/info/alternates::
  71         This file records paths to alternate object stores that
  72         this object store borrows objects from, one pathname per
  73         line. Note that not only native Git tools use it locally,
  74         but the HTTP fetcher also tries to use it remotely; this
  75         will usually work if you have relative paths (relative
  76         to the object database, not to the repository!) in your
  77         alternates file, but it will not work if you use absolute
  78         paths unless the absolute path in filesystem and web URL
  79         is the same. See also 'objects/info/http-alternates'.
  80
  81 objects/info/http-alternates::
  82         This file records URLs to alternate object stores that
  83         this object store borrows objects from, to be used when
  84         the repository is fetched over HTTP.
  85
  86 refs::
  87         References are stored in subdirectories of this
  88         directory.  The `git prune` command knows to keep
  89         objects reachable from refs found in this directory and
  90         its subdirectories.
  91
  92 refs/heads/`name`::
  93         records tip-of-the-tree commit objects of branch `name`
  94
  95 refs/tags/`name`::
  96         records any object name (not necessarily a commit
  97         object, or a tag object that points at a commit object).
  98
  99 refs/remotes/`name`::
 100         records tip-of-the-tree commit objects of branches copied
 101         from a remote repository.
 102
 103 packed-refs::
 104         records the same information as refs/heads/, refs/tags/,
 105         and friends record in a more efficient way.  See
 106         linkgit:git-pack-refs[1].
 107
 108 HEAD::
 109         A symref (see glossary) to the `refs/heads/` namespace
 110         describing the currently active branch.  It does not mean
 111         much if the repository is not associated with any working tree
 112         (i.e. a 'bare' repository), but a valid git repository
 113         *must* have the HEAD file; some porcelains may use it to
 114         guess the designated "default" branch of the repository
 115         (usually 'master').  It is legal if the named branch
 116         'name' does not (yet) exist.  In some legacy setups, it is
 117         a symbolic link instead of a symref that points at the current
 118         branch.
 119 +
 120 HEAD can also record a specific commit directly, instead of
 121 being a symref to point at the current branch.  Such a state
 122 is often called 'detached HEAD', and almost all commands work
 123 identically as normal.  See linkgit:git-checkout[1] for
 124 details.
 125
 126 branches::
 127         A slightly deprecated way to store shorthands to be used
 128         to specify URL to `git fetch`, `git pull` and `git push`
 129         commands is to store a file in `branches/<name>` and
 130         give 'name' to these commands in place of 'repository'
 131         argument.
 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, they need to be made executable.
 138         Read linkgit:githooks[5][hooks] for more details about
 139         each hook.
 140
 141 index::
 142         The current index file for the repository.  It is
 143         usually not found in a bare repository.
 144
 145 info::
 146         Additional information about the repository is recorded
 147         in this directory.
 148
 149 info/refs::
 150         This file helps dumb transports discover what refs are
 151         available in this repository.  If the repository is
 152         published for dumb transports, this file should be
 153         regenerated by `git update-server-info` every time a tag
 154         or branch is created or modified.  This is normally done
 155         from the `hooks/update` hook, which is run by the
 156         `git-receive-pack` command when you `git push` into the
 157         repository.
 158
 159 info/grafts::
 160         This file records fake commit ancestry information, to
 161         pretend the set of parents a commit has is different
 162         from how the commit was actually created.  One record
 163         per line describes a commit and its fake parents by
 164         listing their 40-byte hexadecimal object names separated
 165         by a space and terminated by a newline.
 166
 167 info/exclude::
 168         This file, by convention among Porcelains, stores the
 169         exclude pattern list. `.gitignore` is the per-directory
 170         ignore file.  `git status`, `git add`, `git rm` and `git
 171         clean` look at it but the core git commands do not look
 172         at it.  See also: linkgit:gitignore[5].
 173
 174 remotes::
 175         Stores shorthands to be used to give URL and default
 176         refnames to interact with remote repository to `git
 177         fetch`, `git pull` and `git push` commands.
 178
 179 logs::
 180         Records of changes made to refs are stored in this
 181         directory.  See the documentation on git-update-ref
 182         for more information.
 183
 184 logs/refs/heads/`name`::
 185         Records all changes made to the branch tip named `name`.
 186
 187 logs/refs/tags/`name`::
 188         Records all changes made to the tag named `name`.
 189
 190 shallow::
 191         This is similar to `info/grafts` but is internally used
 192         and maintained by shallow clone mechanism.  See `--depth`
 193         option to linkgit:git-clone[1] and linkgit:git-fetch[1].
 194
 195 SEE ALSO
 196 --------
 197 linkgit:git-init[1],
 198 linkgit:git-clone[1],
 199 linkgit:git-fetch[1],
 200 linkgit:git-pack-refs[1],
 201 linkgit:git-gc[1],
 202 linkgit:git-checkout[1],
 203 linkgit:gitglossary[7],
 204 link:user-manual.html[The Git User's Manual]
 205
 206 GIT
 207 ---
 208 Part of the linkgit:git[1] suite.