doc/source/en/TortoiseGit/git_doc/gitrepository-layout.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="gitrepository-layout(5)">\r
   5 <articleinfo>\r
   6     <title>gitrepository-layout(5)</title>\r
   7 <indexterm>\r
   8 <primary>gitrepository-layout(5)</primary>\r
   9 </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>gitrepository-layout - Git Repository Layout</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <simpara>$GIT_DIR/*</simpara>\r
  18 </simplesect>\r
  19 <simplesect id="_description">\r
  20 <title>DESCRIPTION</title>\r
  21 <simpara>You may find these things in your git repository (<emphasis>.git</emphasis>\r
  22 directory for a repository associated with your working tree, or\r
  23 <emphasis>&lt;project&gt;.git</emphasis> directory for a public <emphasis>bare</emphasis> repository. It is\r
  24 also possible to have a working tree where <emphasis>.git</emphasis> is a plain\r
  25 ASCII file containing <emphasis>gitdir: &lt;path&gt;</emphasis>, i.e. the path to the\r
  26 real git repository).</simpara>\r
  27 <variablelist>\r
  28 <varlistentry>\r
  29 <term>\r
  30 objects\r
  31 </term>\r
  32 <listitem>\r
  33 <simpara>\r
  34         Object store associated with this repository.  Usually\r
  35         an object store is self sufficient (i.e. all the objects\r
  36         that are referred to by an object found in it are also\r
  37         found in it), but there are a few ways to violate it.\r
  38 </simpara>\r
  39 <orderedlist numeration="arabic">\r
  40 <listitem>\r
  41 <simpara>\r
  42 You could have an incomplete but locally usable repository\r
  43 by creating a shallow clone.  See <xref linkend="git-clone(1)" />.\r
  44 </simpara>\r
  45 </listitem>\r
  46 <listitem>\r
  47 <simpara>\r
  48 You could be using the <emphasis>objects/info/alternates</emphasis> or\r
  49 <emphasis>$GIT_ALTERNATE_OBJECT_DIRECTORIES</emphasis> mechanisms to <emphasis>borrow</emphasis>\r
  50 objects from other object stores.  A repository with this kind\r
  51 of incomplete object store is not suitable to be published for\r
  52 use with dumb transports but otherwise is OK as long as\r
  53 <emphasis>objects/info/alternates</emphasis> points at the object stores it\r
  54 borrows from.\r
  55 </simpara>\r
  56 </listitem>\r
  57 </orderedlist>\r
  58 </listitem>\r
  59 </varlistentry>\r
  60 <varlistentry>\r
  61 <term>\r
  62 objects/[0-9a-f][0-9a-f]\r
  63 </term>\r
  64 <listitem>\r
  65 <simpara>\r
  66         A newly created object is stored in its own file.\r
  67         The objects are splayed over 256 subdirectories using\r
  68         the first two characters of the sha1 object name to\r
  69         keep the number of directory entries in <emphasis>objects</emphasis>\r
  70         itself to a manageable number. Objects found\r
  71         here are often called <emphasis>unpacked</emphasis> (or <emphasis>loose</emphasis>) objects.\r
  72 </simpara>\r
  73 </listitem>\r
  74 </varlistentry>\r
  75 <varlistentry>\r
  76 <term>\r
  77 objects/pack\r
  78 </term>\r
  79 <listitem>\r
  80 <simpara>\r
  81         Packs (files that store many object in compressed form,\r
  82         along with index files to allow them to be randomly\r
  83         accessed) are found in this directory.\r
  84 </simpara>\r
  85 </listitem>\r
  86 </varlistentry>\r
  87 <varlistentry>\r
  88 <term>\r
  89 objects/info\r
  90 </term>\r
  91 <listitem>\r
  92 <simpara>\r
  93         Additional information about the object store is\r
  94         recorded in this directory.\r
  95 </simpara>\r
  96 </listitem>\r
  97 </varlistentry>\r
  98 <varlistentry>\r
  99 <term>\r
 100 objects/info/packs\r
 101 </term>\r
 102 <listitem>\r
 103 <simpara>\r
 104         This file is to help dumb transports discover what packs\r
 105         are available in this object store.  Whenever a pack is\r
 106         added or removed, <emphasis>git update-server-info</emphasis> should be run\r
 107         to keep this file up-to-date if the repository is\r
 108         published for dumb transports.  <emphasis>git repack</emphasis> does this\r
 109         by default.\r
 110 </simpara>\r
 111 </listitem>\r
 112 </varlistentry>\r
 113 <varlistentry>\r
 114 <term>\r
 115 objects/info/alternates\r
 116 </term>\r
 117 <listitem>\r
 118 <simpara>\r
 119         This file records paths to alternate object stores that\r
 120         this object store borrows objects from, one pathname per\r
 121         line. Note that not only native Git tools use it locally,\r
 122         but the HTTP fetcher also tries to use it remotely; this\r
 123         will usually work if you have relative paths (relative\r
 124         to the object database, not to the repository!) in your\r
 125         alternates file, but it will not work if you use absolute\r
 126         paths unless the absolute path in filesystem and web URL\r
 127         is the same. See also <emphasis>objects/info/http-alternates</emphasis>.\r
 128 </simpara>\r
 129 </listitem>\r
 130 </varlistentry>\r
 131 <varlistentry>\r
 132 <term>\r
 133 objects/info/http-alternates\r
 134 </term>\r
 135 <listitem>\r
 136 <simpara>\r
 137         This file records URLs to alternate object stores that\r
 138         this object store borrows objects from, to be used when\r
 139         the repository is fetched over HTTP.\r
 140 </simpara>\r
 141 </listitem>\r
 142 </varlistentry>\r
 143 <varlistentry>\r
 144 <term>\r
 145 refs\r
 146 </term>\r
 147 <listitem>\r
 148 <simpara>\r
 149         References are stored in subdirectories of this\r
 150         directory.  The <emphasis>git prune</emphasis> command knows to preserve\r
 151         objects reachable from refs found in this directory and\r
 152         its subdirectories.\r
 153 </simpara>\r
 154 </listitem>\r
 155 </varlistentry>\r
 156 <varlistentry>\r
 157 <term>\r
 158 refs/heads/<emphasis>name</emphasis>\r
 159 </term>\r
 160 <listitem>\r
 161 <simpara>\r
 162         records tip-of-the-tree commit objects of branch <emphasis>name</emphasis>\r
 163 </simpara>\r
 164 </listitem>\r
 165 </varlistentry>\r
 166 <varlistentry>\r
 167 <term>\r
 168 refs/tags/<emphasis>name</emphasis>\r
 169 </term>\r
 170 <listitem>\r
 171 <simpara>\r
 172         records any object name (not necessarily a commit\r
 173         object, or a tag object that points at a commit object).\r
 174 </simpara>\r
 175 </listitem>\r
 176 </varlistentry>\r
 177 <varlistentry>\r
 178 <term>\r
 179 refs/remotes/<emphasis>name</emphasis>\r
 180 </term>\r
 181 <listitem>\r
 182 <simpara>\r
 183         records tip-of-the-tree commit objects of branches copied\r
 184         from a remote repository.\r
 185 </simpara>\r
 186 </listitem>\r
 187 </varlistentry>\r
 188 <varlistentry>\r
 189 <term>\r
 190 packed-refs\r
 191 </term>\r
 192 <listitem>\r
 193 <simpara>\r
 194         records the same information as refs/heads/, refs/tags/,\r
 195         and friends record in a more efficient way.  See\r
 196         <xref linkend="git-pack-refs(1)" />.\r
 197 </simpara>\r
 198 </listitem>\r
 199 </varlistentry>\r
 200 <varlistentry>\r
 201 <term>\r
 202 HEAD\r
 203 </term>\r
 204 <listitem>\r
 205 <simpara>\r
 206         A symref (see glossary) to the <emphasis>refs/heads/</emphasis> namespace\r
 207         describing the currently active branch.  It does not mean\r
 208         much if the repository is not associated with any working tree\r
 209         (i.e. a <emphasis>bare</emphasis> repository), but a valid git repository\r
 210         <emphasis role="strong">must</emphasis> have the HEAD file; some porcelains may use it to\r
 211         guess the designated "default" branch of the repository\r
 212         (usually <emphasis>master</emphasis>).  It is legal if the named branch\r
 213         <emphasis>name</emphasis> does not (yet) exist.  In some legacy setups, it is\r
 214         a symbolic link instead of a symref that points at the current\r
 215         branch.\r
 216 </simpara>\r
 217 <simpara>HEAD can also record a specific commit directly, instead of\r
 218 being a symref to point at the current branch.  Such a state\r
 219 is often called <emphasis>detached HEAD.</emphasis>  See <xref linkend="git-checkout(1)" />\r
 220 for details.</simpara>\r
 221 </listitem>\r
 222 </varlistentry>\r
 223 <varlistentry>\r
 224 <term>\r
 225 branches\r
 226 </term>\r
 227 <listitem>\r
 228 <simpara>\r
 229         A slightly deprecated way to store shorthands to be used\r
 230         to specify a URL to <emphasis>git fetch</emphasis>, <emphasis>git pull</emphasis> and <emphasis>git push</emphasis>.\r
 231         A file can be stored as <emphasis>branches/&lt;name&gt;</emphasis> and then\r
 232         <emphasis>name</emphasis> can be given to these commands in place of\r
 233         <emphasis>repository</emphasis> argument.  See the REMOTES section in\r
 234         <xref linkend="git-fetch(1)" /> for details.  This mechanism is legacy\r
 235         and not likely to be found in modern repositories.\r
 236 </simpara>\r
 237 </listitem>\r
 238 </varlistentry>\r
 239 <varlistentry>\r
 240 <term>\r
 241 hooks\r
 242 </term>\r
 243 <listitem>\r
 244 <simpara>\r
 245         Hooks are customization scripts used by various git\r
 246         commands.  A handful of sample hooks are installed when\r
 247         <emphasis>git init</emphasis> is run, but all of them are disabled by\r
 248         default.  To enable, the <emphasis>.sample</emphasis> suffix has to be\r
 249         removed from the filename by renaming.\r
 250         Read <xref linkend="githooks(5)" /> for more details about\r
 251         each hook.\r
 252 </simpara>\r
 253 </listitem>\r
 254 </varlistentry>\r
 255 <varlistentry>\r
 256 <term>\r
 257 index\r
 258 </term>\r
 259 <listitem>\r
 260 <simpara>\r
 261         The current index file for the repository.  It is\r
 262         usually not found in a bare repository.\r
 263 </simpara>\r
 264 </listitem>\r
 265 </varlistentry>\r
 266 <varlistentry>\r
 267 <term>\r
 268 info\r
 269 </term>\r
 270 <listitem>\r
 271 <simpara>\r
 272         Additional information about the repository is recorded\r
 273         in this directory.\r
 274 </simpara>\r
 275 </listitem>\r
 276 </varlistentry>\r
 277 <varlistentry>\r
 278 <term>\r
 279 info/refs\r
 280 </term>\r
 281 <listitem>\r
 282 <simpara>\r
 283         This file helps dumb transports discover what refs are\r
 284         available in this repository.  If the repository is\r
 285         published for dumb transports, this file should be\r
 286         regenerated by <emphasis>git update-server-info</emphasis> every time a tag\r
 287         or branch is created or modified.  This is normally done\r
 288         from the <emphasis>hooks/update</emphasis> hook, which is run by the\r
 289         <emphasis>git-receive-pack</emphasis> command when you <emphasis>git push</emphasis> into the\r
 290         repository.\r
 291 </simpara>\r
 292 </listitem>\r
 293 </varlistentry>\r
 294 <varlistentry>\r
 295 <term>\r
 296 info/grafts\r
 297 </term>\r
 298 <listitem>\r
 299 <simpara>\r
 300         This file records fake commit ancestry information, to\r
 301         pretend the set of parents a commit has is different\r
 302         from how the commit was actually created.  One record\r
 303         per line describes a commit and its fake parents by\r
 304         listing their 40-byte hexadecimal object names separated\r
 305         by a space and terminated by a newline.\r
 306 </simpara>\r
 307 </listitem>\r
 308 </varlistentry>\r
 309 <varlistentry>\r
 310 <term>\r
 311 info/exclude\r
 312 </term>\r
 313 <listitem>\r
 314 <simpara>\r
 315         This file, by convention among Porcelains, stores the\r
 316         exclude pattern list. <emphasis>.gitignore</emphasis> is the per-directory\r
 317         ignore file.  <emphasis>git status</emphasis>, <emphasis>git add</emphasis>, <emphasis>git rm</emphasis> and\r
 318         <emphasis>git clean</emphasis> look at it but the core git commands do not look\r
 319         at it.  See also: <xref linkend="gitignore(5)" />.\r
 320 </simpara>\r
 321 </listitem>\r
 322 </varlistentry>\r
 323 <varlistentry>\r
 324 <term>\r
 325 remotes\r
 326 </term>\r
 327 <listitem>\r
 328 <simpara>\r
 329         Stores shorthands for URL and default refnames for use\r
 330         when interacting with remote repositories via <emphasis>git fetch</emphasis>,\r
 331         <emphasis>git pull</emphasis> and <emphasis>git push</emphasis> commands.  See the REMOTES section\r
 332         in <xref linkend="git-fetch(1)" /> for details.  This mechanism is legacy\r
 333         and not likely to be found in modern repositories.\r
 334 </simpara>\r
 335 </listitem>\r
 336 </varlistentry>\r
 337 <varlistentry>\r
 338 <term>\r
 339 logs\r
 340 </term>\r
 341 <listitem>\r
 342 <simpara>\r
 343         Records of changes made to refs are stored in this\r
 344         directory.  See <xref linkend="git-update-ref(1)" />\r
 345         for more information.\r
 346 </simpara>\r
 347 </listitem>\r
 348 </varlistentry>\r
 349 <varlistentry>\r
 350 <term>\r
 351 logs/refs/heads/<emphasis>name</emphasis>\r
 352 </term>\r
 353 <listitem>\r
 354 <simpara>\r
 355         Records all changes made to the branch tip named <emphasis>name</emphasis>.\r
 356 </simpara>\r
 357 </listitem>\r
 358 </varlistentry>\r
 359 <varlistentry>\r
 360 <term>\r
 361 logs/refs/tags/<emphasis>name</emphasis>\r
 362 </term>\r
 363 <listitem>\r
 364 <simpara>\r
 365         Records all changes made to the tag named <emphasis>name</emphasis>.\r
 366 </simpara>\r
 367 </listitem>\r
 368 </varlistentry>\r
 369 <varlistentry>\r
 370 <term>\r
 371 shallow\r
 372 </term>\r
 373 <listitem>\r
 374 <simpara>\r
 375         This is similar to <emphasis>info/grafts</emphasis> but is internally used\r
 376         and maintained by shallow clone mechanism.  See <emphasis>--depth</emphasis>\r
 377         option to <xref linkend="git-clone(1)" /> and <xref linkend="git-fetch(1)" />.\r
 378 </simpara>\r
 379 </listitem>\r
 380 </varlistentry>\r
 381 </variablelist>\r
 382 </simplesect>\r
 383 <simplesect id="_see_also">\r
 384 <title>SEE ALSO</title>\r
 385 <simpara><xref linkend="git-init(1)" />,\r
 386 <xref linkend="git-clone(1)" />,\r
 387 <xref linkend="git-fetch(1)" />,\r
 388 <xref linkend="git-pack-refs(1)" />,\r
 389 <xref linkend="git-gc(1)" />,\r
 390 <xref linkend="git-checkout(1)" />,\r
 391 <xref linkend="gitglossary(7)" />,\r
 392 link:user-manual.html[The Git User's Manual]</simpara>\r
 393 </simplesect>\r
 394 <simplesect id="_git">\r
 395 <title>GIT</title>\r
 396 <simpara>Part of the <xref linkend="git(1)" /> suite.</simpara>\r
 397 </simplesect>\r
 398 </article>\r