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

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <sect2 lang="en" id="gitrepository-layout(5)">\r
   5     <title>gitrepository-layout(5)</title>\r
   6 <indexterm>\r
   7 <primary>gitrepository-layout(5)</primary>\r
   8 </indexterm>\r
   9 <simplesect id="gitrepository-layout(5)__name">\r
  10 <title>NAME</title>\r
  11 <simpara>gitrepository-layout - Git Repository Layout</simpara>\r
  12 </simplesect>\r
  13 <simplesect id="gitrepository-layout(5)__synopsis">\r
  14 <title>SYNOPSIS</title>\r
  15 <simpara>$GIT_DIR/*</simpara>\r
  16 </simplesect>\r
  17 <simplesect id="gitrepository-layout(5)__description">\r
  18 <title>DESCRIPTION</title>\r
  19 <simpara>A Git repository comes in two different flavours:</simpara>\r
  20 <itemizedlist>\r
  21 <listitem>\r
  22 <simpara>\r
  23 a <emphasis>.git</emphasis> directory at the root of the working tree;\r
  24 </simpara>\r
  25 </listitem>\r
  26 <listitem>\r
  27 <simpara>\r
  28 a <emphasis>&lt;project&gt;.git</emphasis> directory that is a <emphasis>bare</emphasis> repository\r
  29    (i.e. without its own working tree), that is typically used for\r
  30    exchanging histories with others by pushing into it and fetching\r
  31    from it.\r
  32 </simpara>\r
  33 </listitem>\r
  34 </itemizedlist>\r
  35 <simpara><emphasis role="strong">Note</emphasis>: Also you can have a plain text file <emphasis>.git</emphasis> at the root of\r
  36 your working tree, containing <emphasis>gitdir: &lt;path&gt;</emphasis> to point at the real\r
  37 directory that has the repository.  This mechanism is often used for\r
  38 a working tree of a submodule checkout, to allow you in the\r
  39 containing superproject to <emphasis>git checkout</emphasis> a branch that does not\r
  40 have the submodule.  The <emphasis>checkout</emphasis> has to remove the entire\r
  41 submodule working tree, without losing the submodule repository.</simpara>\r
  42 <simpara>These things may exist in a Git repository.</simpara>\r
  43 <variablelist>\r
  44 <varlistentry>\r
  45 <term>\r
  46 objects\r
  47 </term>\r
  48 <listitem>\r
  49 <simpara>\r
  50         Object store associated with this repository.  Usually\r
  51         an object store is self sufficient (i.e. all the objects\r
  52         that are referred to by an object found in it are also\r
  53         found in it), but there are a few ways to violate it.\r
  54 </simpara>\r
  55 <orderedlist numeration="arabic">\r
  56 <listitem>\r
  57 <simpara>\r
  58 You could have an incomplete but locally usable repository\r
  59 by creating a shallow clone.  See <xref linkend="git-clone(1)" />.\r
  60 </simpara>\r
  61 </listitem>\r
  62 <listitem>\r
  63 <simpara>\r
  64 You could be using the <emphasis>objects/info/alternates</emphasis> or\r
  65 <emphasis>$GIT_ALTERNATE_OBJECT_DIRECTORIES</emphasis> mechanisms to <emphasis>borrow</emphasis>\r
  66 objects from other object stores.  A repository with this kind\r
  67 of incomplete object store is not suitable to be published for\r
  68 use with dumb transports but otherwise is OK as long as\r
  69 <emphasis>objects/info/alternates</emphasis> points at the object stores it\r
  70 borrows from.\r
  71 </simpara>\r
  72 <simpara>This directory is ignored if $GIT_COMMON_DIR is set and\r
  73 "$GIT_COMMON_DIR/objects" will be used instead.</simpara>\r
  74 </listitem>\r
  75 </orderedlist>\r
  76 </listitem>\r
  77 </varlistentry>\r
  78 <varlistentry>\r
  79 <term>\r
  80 objects/[0-9a-f][0-9a-f]\r
  81 </term>\r
  82 <listitem>\r
  83 <simpara>\r
  84         A newly created object is stored in its own file.\r
  85         The objects are splayed over 256 subdirectories using\r
  86         the first two characters of the sha1 object name to\r
  87         keep the number of directory entries in <emphasis>objects</emphasis>\r
  88         itself to a manageable number. Objects found\r
  89         here are often called <emphasis>unpacked</emphasis> (or <emphasis>loose</emphasis>) objects.\r
  90 </simpara>\r
  91 </listitem>\r
  92 </varlistentry>\r
  93 <varlistentry>\r
  94 <term>\r
  95 objects/pack\r
  96 </term>\r
  97 <listitem>\r
  98 <simpara>\r
  99         Packs (files that store many object in compressed form,\r
 100         along with index files to allow them to be randomly\r
 101         accessed) are found in this directory.\r
 102 </simpara>\r
 103 </listitem>\r
 104 </varlistentry>\r
 105 <varlistentry>\r
 106 <term>\r
 107 objects/info\r
 108 </term>\r
 109 <listitem>\r
 110 <simpara>\r
 111         Additional information about the object store is\r
 112         recorded in this directory.\r
 113 </simpara>\r
 114 </listitem>\r
 115 </varlistentry>\r
 116 <varlistentry>\r
 117 <term>\r
 118 objects/info/packs\r
 119 </term>\r
 120 <listitem>\r
 121 <simpara>\r
 122         This file is to help dumb transports discover what packs\r
 123         are available in this object store.  Whenever a pack is\r
 124         added or removed, <emphasis>git update-server-info</emphasis> should be run\r
 125         to keep this file up-to-date if the repository is\r
 126         published for dumb transports.  <emphasis>git repack</emphasis> does this\r
 127         by default.\r
 128 </simpara>\r
 129 </listitem>\r
 130 </varlistentry>\r
 131 <varlistentry>\r
 132 <term>\r
 133 objects/info/alternates\r
 134 </term>\r
 135 <listitem>\r
 136 <simpara>\r
 137         This file records paths to alternate object stores that\r
 138         this object store borrows objects from, one pathname per\r
 139         line. Note that not only native Git tools use it locally,\r
 140         but the HTTP fetcher also tries to use it remotely; this\r
 141         will usually work if you have relative paths (relative\r
 142         to the object database, not to the repository!) in your\r
 143         alternates file, but it will not work if you use absolute\r
 144         paths unless the absolute path in filesystem and web URL\r
 145         is the same. See also <emphasis>objects/info/http-alternates</emphasis>.\r
 146 </simpara>\r
 147 </listitem>\r
 148 </varlistentry>\r
 149 <varlistentry>\r
 150 <term>\r
 151 objects/info/http-alternates\r
 152 </term>\r
 153 <listitem>\r
 154 <simpara>\r
 155         This file records URLs to alternate object stores that\r
 156         this object store borrows objects from, to be used when\r
 157         the repository is fetched over HTTP.\r
 158 </simpara>\r
 159 </listitem>\r
 160 </varlistentry>\r
 161 <varlistentry>\r
 162 <term>\r
 163 refs\r
 164 </term>\r
 165 <listitem>\r
 166 <simpara>\r
 167         References are stored in subdirectories of this\r
 168         directory.  The <emphasis>git prune</emphasis> command knows to preserve\r
 169         objects reachable from refs found in this directory and\r
 170         its subdirectories. This directory is ignored if $GIT_COMMON_DIR\r
 171         is set and "$GIT_COMMON_DIR/refs" will be used instead.\r
 172 </simpara>\r
 173 </listitem>\r
 174 </varlistentry>\r
 175 <varlistentry>\r
 176 <term>\r
 177 refs/heads/<emphasis>name</emphasis>\r
 178 </term>\r
 179 <listitem>\r
 180 <simpara>\r
 181         records tip-of-the-tree commit objects of branch <emphasis>name</emphasis>\r
 182 </simpara>\r
 183 </listitem>\r
 184 </varlistentry>\r
 185 <varlistentry>\r
 186 <term>\r
 187 refs/tags/<emphasis>name</emphasis>\r
 188 </term>\r
 189 <listitem>\r
 190 <simpara>\r
 191         records any object name (not necessarily a commit\r
 192         object, or a tag object that points at a commit object).\r
 193 </simpara>\r
 194 </listitem>\r
 195 </varlistentry>\r
 196 <varlistentry>\r
 197 <term>\r
 198 refs/remotes/<emphasis>name</emphasis>\r
 199 </term>\r
 200 <listitem>\r
 201 <simpara>\r
 202         records tip-of-the-tree commit objects of branches copied\r
 203         from a remote repository.\r
 204 </simpara>\r
 205 </listitem>\r
 206 </varlistentry>\r
 207 <varlistentry>\r
 208 <term>\r
 209 refs/replace/<emphasis>&lt;obj-sha1&gt;</emphasis>\r
 210 </term>\r
 211 <listitem>\r
 212 <simpara>\r
 213         records the SHA-1 of the object that replaces <emphasis>&lt;obj-sha1&gt;</emphasis>.\r
 214         This is similar to info/grafts and is internally used and\r
 215         maintained by <xref linkend="git-replace(1)" />. Such refs can be exchanged\r
 216         between repositories while grafts are not.\r
 217 </simpara>\r
 218 </listitem>\r
 219 </varlistentry>\r
 220 <varlistentry>\r
 221 <term>\r
 222 packed-refs\r
 223 </term>\r
 224 <listitem>\r
 225 <simpara>\r
 226         records the same information as refs/heads/, refs/tags/,\r
 227         and friends record in a more efficient way.  See\r
 228         <xref linkend="git-pack-refs(1)" />. This file is ignored if $GIT_COMMON_DIR\r
 229         is set and "$GIT_COMMON_DIR/packed-refs" will be used instead.\r
 230 </simpara>\r
 231 </listitem>\r
 232 </varlistentry>\r
 233 <varlistentry>\r
 234 <term>\r
 235 HEAD\r
 236 </term>\r
 237 <listitem>\r
 238 <simpara>\r
 239         A symref (see glossary) to the <emphasis>refs/heads/</emphasis> namespace\r
 240         describing the currently active branch.  It does not mean\r
 241         much if the repository is not associated with any working tree\r
 242         (i.e. a <emphasis>bare</emphasis> repository), but a valid Git repository\r
 243         <emphasis role="strong">must</emphasis> have the HEAD file; some porcelains may use it to\r
 244         guess the designated "default" branch of the repository\r
 245         (usually <emphasis>master</emphasis>).  It is legal if the named branch\r
 246         <emphasis>name</emphasis> does not (yet) exist.  In some legacy setups, it is\r
 247         a symbolic link instead of a symref that points at the current\r
 248         branch.\r
 249 </simpara>\r
 250 <simpara>HEAD can also record a specific commit directly, instead of\r
 251 being a symref to point at the current branch.  Such a state\r
 252 is often called <emphasis>detached HEAD.</emphasis>  See <xref linkend="git-checkout(1)" />\r
 253 for details.</simpara>\r
 254 </listitem>\r
 255 </varlistentry>\r
 256 <varlistentry>\r
 257 <term>\r
 258 config\r
 259 </term>\r
 260 <listitem>\r
 261 <simpara>\r
 262         Repository specific configuration file. This file is ignored\r
 263         if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be\r
 264         used instead.\r
 265 </simpara>\r
 266 </listitem>\r
 267 </varlistentry>\r
 268 <varlistentry>\r
 269 <term>\r
 270 branches\r
 271 </term>\r
 272 <listitem>\r
 273 <simpara>\r
 274         A slightly deprecated way to store shorthands to be used\r
 275         to specify a URL to <emphasis>git fetch</emphasis>, <emphasis>git pull</emphasis> and <emphasis>git push</emphasis>.\r
 276         A file can be stored as <emphasis>branches/&lt;name&gt;</emphasis> and then\r
 277         <emphasis>name</emphasis> can be given to these commands in place of\r
 278         <emphasis>repository</emphasis> argument.  See the REMOTES section in\r
 279         <xref linkend="git-fetch(1)" /> for details.  This mechanism is legacy\r
 280         and not likely to be found in modern repositories. This\r
 281         directory is ignored if $GIT_COMMON_DIR is set and\r
 282         "$GIT_COMMON_DIR/branches" will be used instead.\r
 283 </simpara>\r
 284 </listitem>\r
 285 </varlistentry>\r
 286 <varlistentry>\r
 287 <term>\r
 288 hooks\r
 289 </term>\r
 290 <listitem>\r
 291 <simpara>\r
 292         Hooks are customization scripts used by various Git\r
 293         commands.  A handful of sample hooks are installed when\r
 294         <emphasis>git init</emphasis> is run, but all of them are disabled by\r
 295         default.  To enable, the <emphasis>.sample</emphasis> suffix has to be\r
 296         removed from the filename by renaming.\r
 297         Read <xref linkend="githooks(5)" /> for more details about\r
 298         each hook. This directory is ignored if $GIT_COMMON_DIR is set\r
 299         and "$GIT_COMMON_DIR/hooks" will be used instead.\r
 300 </simpara>\r
 301 </listitem>\r
 302 </varlistentry>\r
 303 <varlistentry>\r
 304 <term>\r
 305 index\r
 306 </term>\r
 307 <listitem>\r
 308 <simpara>\r
 309         The current index file for the repository.  It is\r
 310         usually not found in a bare repository.\r
 311 </simpara>\r
 312 </listitem>\r
 313 </varlistentry>\r
 314 <varlistentry>\r
 315 <term>\r
 316 sharedindex.&lt;SHA-1&gt;\r
 317 </term>\r
 318 <listitem>\r
 319 <simpara>\r
 320         The shared index part, to be referenced by $GIT_DIR/index and\r
 321         other temporary index files. Only valid in split index mode.\r
 322 </simpara>\r
 323 </listitem>\r
 324 </varlistentry>\r
 325 <varlistentry>\r
 326 <term>\r
 327 info\r
 328 </term>\r
 329 <listitem>\r
 330 <simpara>\r
 331         Additional information about the repository is recorded\r
 332         in this directory. This directory is ignored if $GIT_COMMON_DIR\r
 333         is set and "$GIT_COMMON_DIR/index" will be used instead.\r
 334 </simpara>\r
 335 </listitem>\r
 336 </varlistentry>\r
 337 <varlistentry>\r
 338 <term>\r
 339 info/refs\r
 340 </term>\r
 341 <listitem>\r
 342 <simpara>\r
 343         This file helps dumb transports discover what refs are\r
 344         available in this repository.  If the repository is\r
 345         published for dumb transports, this file should be\r
 346         regenerated by <emphasis>git update-server-info</emphasis> every time a tag\r
 347         or branch is created or modified.  This is normally done\r
 348         from the <emphasis>hooks/update</emphasis> hook, which is run by the\r
 349         <emphasis>git-receive-pack</emphasis> command when you <emphasis>git push</emphasis> into the\r
 350         repository.\r
 351 </simpara>\r
 352 </listitem>\r
 353 </varlistentry>\r
 354 <varlistentry>\r
 355 <term>\r
 356 info/grafts\r
 357 </term>\r
 358 <listitem>\r
 359 <simpara>\r
 360         This file records fake commit ancestry information, to\r
 361         pretend the set of parents a commit has is different\r
 362         from how the commit was actually created.  One record\r
 363         per line describes a commit and its fake parents by\r
 364         listing their 40-byte hexadecimal object names separated\r
 365         by a space and terminated by a newline.\r
 366 </simpara>\r
 367 <simpara>Note that the grafts mechanism is outdated and can lead to problems\r
 368 transferring objects between repositories; see <xref linkend="git-replace(1)" />\r
 369 for a more flexible and robust system to do the same thing.</simpara>\r
 370 </listitem>\r
 371 </varlistentry>\r
 372 <varlistentry>\r
 373 <term>\r
 374 info/exclude\r
 375 </term>\r
 376 <listitem>\r
 377 <simpara>\r
 378         This file, by convention among Porcelains, stores the\r
 379         exclude pattern list. <emphasis>.gitignore</emphasis> is the per-directory\r
 380         ignore file.  <emphasis>git status</emphasis>, <emphasis>git add</emphasis>, <emphasis>git rm</emphasis> and\r
 381         <emphasis>git clean</emphasis> look at it but the core Git commands do not look\r
 382         at it.  See also: <xref linkend="gitignore(5)" />.\r
 383 </simpara>\r
 384 </listitem>\r
 385 </varlistentry>\r
 386 <varlistentry>\r
 387 <term>\r
 388 info/sparse-checkout\r
 389 </term>\r
 390 <listitem>\r
 391 <simpara>\r
 392         This file stores sparse checkout patterns.\r
 393         See also: <xref linkend="git-read-tree(1)" />.\r
 394 </simpara>\r
 395 </listitem>\r
 396 </varlistentry>\r
 397 <varlistentry>\r
 398 <term>\r
 399 remotes\r
 400 </term>\r
 401 <listitem>\r
 402 <simpara>\r
 403         Stores shorthands for URL and default refnames for use\r
 404         when interacting with remote repositories via <emphasis>git fetch</emphasis>,\r
 405         <emphasis>git pull</emphasis> and <emphasis>git push</emphasis> commands.  See the REMOTES section\r
 406         in <xref linkend="git-fetch(1)" /> for details.  This mechanism is legacy\r
 407         and not likely to be found in modern repositories. This\r
 408         directory is ignored if $GIT_COMMON_DIR is set and\r
 409         "$GIT_COMMON_DIR/remotes" will be used instead.\r
 410 </simpara>\r
 411 </listitem>\r
 412 </varlistentry>\r
 413 <varlistentry>\r
 414 <term>\r
 415 logs\r
 416 </term>\r
 417 <listitem>\r
 418 <simpara>\r
 419         Records of changes made to refs are stored in this directory.\r
 420         See <xref linkend="git-update-ref(1)" /> for more information. This\r
 421         directory is ignored if $GIT_COMMON_DIR is set and\r
 422         "$GIT_COMMON_DIR/logs" will be used instead.\r
 423 </simpara>\r
 424 </listitem>\r
 425 </varlistentry>\r
 426 <varlistentry>\r
 427 <term>\r
 428 logs/refs/heads/<emphasis>name</emphasis>\r
 429 </term>\r
 430 <listitem>\r
 431 <simpara>\r
 432         Records all changes made to the branch tip named <emphasis>name</emphasis>.\r
 433 </simpara>\r
 434 </listitem>\r
 435 </varlistentry>\r
 436 <varlistentry>\r
 437 <term>\r
 438 logs/refs/tags/<emphasis>name</emphasis>\r
 439 </term>\r
 440 <listitem>\r
 441 <simpara>\r
 442         Records all changes made to the tag named <emphasis>name</emphasis>.\r
 443 </simpara>\r
 444 </listitem>\r
 445 </varlistentry>\r
 446 <varlistentry>\r
 447 <term>\r
 448 shallow\r
 449 </term>\r
 450 <listitem>\r
 451 <simpara>\r
 452         This is similar to <emphasis>info/grafts</emphasis> but is internally used\r
 453         and maintained by shallow clone mechanism.  See <emphasis>--depth</emphasis>\r
 454         option to <xref linkend="git-clone(1)" /> and <xref linkend="git-fetch(1)" />. This\r
 455         file is ignored if $GIT_COMMON_DIR is set and\r
 456         "$GIT_COMMON_DIR/shallow" will be used instead.\r
 457 </simpara>\r
 458 </listitem>\r
 459 </varlistentry>\r
 460 <varlistentry>\r
 461 <term>\r
 462 commondir\r
 463 </term>\r
 464 <listitem>\r
 465 <simpara>\r
 466         If this file exists, $GIT_COMMON_DIR (see <xref linkend="git(1)" />) will\r
 467         be set to the path specified in this file if it is not\r
 468         explicitly set. If the specified path is relative, it is\r
 469         relative to $GIT_DIR. The repository with commondir is\r
 470         incomplete without the repository pointed by "commondir".\r
 471 </simpara>\r
 472 </listitem>\r
 473 </varlistentry>\r
 474 <varlistentry>\r
 475 <term>\r
 476 modules\r
 477 </term>\r
 478 <listitem>\r
 479 <simpara>\r
 480         Contains the git-repositories of the submodules.\r
 481 </simpara>\r
 482 </listitem>\r
 483 </varlistentry>\r
 484 <varlistentry>\r
 485 <term>\r
 486 worktrees\r
 487 </term>\r
 488 <listitem>\r
 489 <simpara>\r
 490         Contains administrative data for linked\r
 491         working trees. Each subdirectory contains the working tree-related\r
 492         part of a linked working tree. This directory is ignored if\r
 493         $GIT_COMMON_DIR is set, in which case\r
 494         "$GIT_COMMON_DIR/worktrees" will be used instead.\r
 495 </simpara>\r
 496 </listitem>\r
 497 </varlistentry>\r
 498 <varlistentry>\r
 499 <term>\r
 500 worktrees/&lt;id&gt;/gitdir\r
 501 </term>\r
 502 <listitem>\r
 503 <simpara>\r
 504         A text file containing the absolute path back to the .git file\r
 505         that points to here. This is used to check if the linked\r
 506         repository has been manually removed and there is no need to\r
 507         keep this directory any more. The mtime of this file should be\r
 508         updated every time the linked repository is accessed.\r
 509 </simpara>\r
 510 </listitem>\r
 511 </varlistentry>\r
 512 <varlistentry>\r
 513 <term>\r
 514 worktrees/&lt;id&gt;/locked\r
 515 </term>\r
 516 <listitem>\r
 517 <simpara>\r
 518         If this file exists, the linked working tree may be on a\r
 519         portable device and not available. The presence of this file\r
 520         prevents <emphasis>worktrees/&lt;id&gt;</emphasis> from being pruned either automatically\r
 521         or manually by <emphasis>git worktree prune</emphasis>. The file may contain a string\r
 522         explaining why the repository is locked.\r
 523 </simpara>\r
 524 </listitem>\r
 525 </varlistentry>\r
 526 <varlistentry>\r
 527 <term>\r
 528 worktrees/&lt;id&gt;/link\r
 529 </term>\r
 530 <listitem>\r
 531 <simpara>\r
 532         If this file exists, it is a hard link to the linked .git\r
 533         file. It is used to detect if the linked repository is\r
 534         manually removed.\r
 535 </simpara>\r
 536 </listitem>\r
 537 </varlistentry>\r
 538 </variablelist>\r
 539 </simplesect>\r
 540 <simplesect id="gitrepository-layout(5)__see_also">\r
 541 <title>SEE ALSO</title>\r
 542 <simpara><xref linkend="git-init(1)" />,\r
 543 <xref linkend="git-clone(1)" />,\r
 544 <xref linkend="git-fetch(1)" />,\r
 545 <xref linkend="git-pack-refs(1)" />,\r
 546 <xref linkend="git-gc(1)" />,\r
 547 <xref linkend="git-checkout(1)" />,\r
 548 <xref linkend="gitglossary(7)" />,\r
 549 link:user-manual.html[The Git User's Manual]</simpara>\r
 550 </simplesect>\r
 551 <simplesect id="gitrepository-layout(5)__git">\r
 552 <title>GIT</title>\r
 553 <simpara>Part of the <xref linkend="git(1)" /> suite.</simpara>\r
 554 </simplesect>\r
 555 </sect2>\r