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, 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 to be used to give URL and default
 177         refnames to interact with remote repository to
 178         'git fetch', 'git pull' and 'git push' commands.
 179
 180 logs::
 181         Records of changes made to refs are stored in this
 182         directory.  See linkgit:git-update-ref[1]
 183         for more information.
 184
 185 logs/refs/heads/`name`::
 186         Records all changes made to the branch tip named `name`.
 187
 188 logs/refs/tags/`name`::
 189         Records all changes made to the tag named `name`.
 190
 191 shallow::
 192         This is similar to `info/grafts` but is internally used
 193         and maintained by shallow clone mechanism.  See `--depth`
 194         option to linkgit:git-clone[1] and linkgit:git-fetch[1].
 195
 196 SEE ALSO
 197 --------
 198 linkgit:git-init[1],
 199 linkgit:git-clone[1],
 200 linkgit:git-fetch[1],
 201 linkgit:git-pack-refs[1],
 202 linkgit:git-gc[1],
 203 linkgit:git-checkout[1],
 204 linkgit:gitglossary[7],
 205 link:user-manual.html[The Git User's Manual]
 206
 207 GIT
 208 ---
 209 Part of the linkgit:git[1] suite.