--- /dev/null
+<?xml version="1.0" encoding="UTF-8"?>\r
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\r
+\r
+<article lang="en" id="gitrepository-layout(5)">\r
+<articleinfo>\r
+ <title>gitrepository-layout(5)</title>\r
+ <indexterm>\r
+ <primary>gitrepository-layout(5)</primary>\r
+ </indexterm>\r
+</articleinfo>\r
+<simplesect id="_name">\r
+<title>NAME</title>\r
+<simpara>gitrepository-layout - Git Repository Layout</simpara>\r
+</simplesect>\r
+<simplesect id="_synopsis">\r
+<title>SYNOPSIS</title>\r
+<simpara>$GIT_DIR/*</simpara>\r
+</simplesect>\r
+<simplesect id="_description">\r
+<title>DESCRIPTION</title>\r
+<simpara>You may find these things in your git repository (<literal>.git</literal>\r
+directory for a repository associated with your working tree, or\r
+<literal><project>.git</literal> directory for a public <emphasis>bare</emphasis> repository. It is\r
+also possible to have a working tree where <literal>.git</literal> is a plain\r
+ascii file containing <literal>gitdir: <path></literal>, i.e. the path to the\r
+real git repository).</simpara>\r
+<variablelist>\r
+<varlistentry>\r
+<term>\r
+objects\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Object store associated with this repository. Usually\r
+ an object store is self sufficient (i.e. all the objects\r
+ that are referred to by an object found in it are also\r
+ found in it), but there are couple of ways to violate\r
+ it.\r
+</simpara>\r
+<orderedlist numeration="arabic">\r
+<listitem>\r
+<simpara>\r
+You could populate the repository by running a commit walker\r
+without <literal>-a</literal> option. Depending on which options are given, you\r
+could have only commit objects without associated blobs and\r
+trees this way, for example. A repository with this kind of\r
+incomplete object store is not suitable to be published to the\r
+outside world but sometimes useful for private repository.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+You also could have an incomplete but locally usable repository\r
+by cloning shallowly. See <xref linkend="git-clone(1)"/>.\r
+</simpara>\r
+</listitem>\r
+<listitem>\r
+<simpara>\r
+You can be using <literal>objects/info/alternates</literal> mechanism, or\r
+<literal>$GIT_ALTERNATE_OBJECT_DIRECTORIES</literal> mechanism to <emphasis>borrow</emphasis>\r
+objects from other object stores. A repository with this kind\r
+of incomplete object store is not suitable to be published for\r
+use with dumb transports but otherwise is OK as long as\r
+<literal>objects/info/alternates</literal> points at the right object stores\r
+it borrows from.\r
+</simpara>\r
+</listitem>\r
+</orderedlist>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+objects/[0-9a-f][0-9a-f]\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Traditionally, each object is stored in its own file.\r
+ They are split into 256 subdirectories using the first\r
+ two letters from its object name to keep the number of\r
+ directory entries <literal>objects</literal> directory itself needs to\r
+ hold. Objects found here are often called <emphasis>unpacked</emphasis>\r
+ (or <emphasis>loose</emphasis>) objects.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+objects/pack\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Packs (files that store many object in compressed form,\r
+ along with index files to allow them to be randomly\r
+ accessed) are found in this directory.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+objects/info\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Additional information about the object store is\r
+ recorded in this directory.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+objects/info/packs\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ This file is to help dumb transports discover what packs\r
+ are available in this object store. Whenever a pack is\r
+ added or removed, <literal>git update-server-info</literal> should be run\r
+ to keep this file up-to-date if the repository is\r
+ published for dumb transports. <emphasis>git-repack</emphasis> does this\r
+ by default.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+objects/info/alternates\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ This file records paths to alternate object stores that\r
+ this object store borrows objects from, one pathname per\r
+ line. Note that not only native Git tools use it locally,\r
+ but the HTTP fetcher also tries to use it remotely; this\r
+ will usually work if you have relative paths (relative\r
+ to the object database, not to the repository!) in your\r
+ alternates file, but it will not work if you use absolute\r
+ paths unless the absolute path in filesystem and web URL\r
+ is the same. See also <emphasis>objects/info/http-alternates</emphasis>.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+objects/info/http-alternates\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ This file records URLs to alternate object stores that\r
+ this object store borrows objects from, to be used when\r
+ the repository is fetched over HTTP.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+refs\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ References are stored in subdirectories of this\r
+ directory. The <emphasis>git-prune</emphasis> command knows to keep\r
+ objects reachable from refs found in this directory and\r
+ its subdirectories.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+refs/heads/<literal>name</literal>\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ records tip-of-the-tree commit objects of branch <literal>name</literal>\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+refs/tags/<literal>name</literal>\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ records any object name (not necessarily a commit\r
+ object, or a tag object that points at a commit object).\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+refs/remotes/<literal>name</literal>\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ records tip-of-the-tree commit objects of branches copied\r
+ from a remote repository.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+packed-refs\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ records the same information as refs/heads/, refs/tags/,\r
+ and friends record in a more efficient way. See\r
+ <xref linkend="git-pack-refs(1)"/>.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+HEAD\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ A symref (see glossary) to the <literal>refs/heads/</literal> namespace\r
+ describing the currently active branch. It does not mean\r
+ much if the repository is not associated with any working tree\r
+ (i.e. a <emphasis>bare</emphasis> repository), but a valid git repository\r
+ <emphasis role="strong">must</emphasis> have the HEAD file; some porcelains may use it to\r
+ guess the designated "default" branch of the repository\r
+ (usually <emphasis>master</emphasis>). It is legal if the named branch\r
+ <emphasis>name</emphasis> does not (yet) exist. In some legacy setups, it is\r
+ a symbolic link instead of a symref that points at the current\r
+ branch.\r
+</simpara>\r
+<simpara>HEAD can also record a specific commit directly, instead of\r
+being a symref to point at the current branch. Such a state\r
+is often called <emphasis>detached HEAD</emphasis>, and almost all commands work\r
+identically as normal. See <xref linkend="git-checkout(1)"/> for\r
+details.</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+branches\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ A slightly deprecated way to store shorthands to be used\r
+ to specify URL to <emphasis>git-fetch</emphasis>, <emphasis>git-pull</emphasis> and <emphasis>git-push</emphasis>\r
+ commands is to store a file in <literal>branches/<name></literal> and\r
+ give <emphasis>name</emphasis> to these commands in place of <emphasis>repository</emphasis>\r
+ argument.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+hooks\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Hooks are customization scripts used by various git\r
+ commands. A handful of sample hooks are installed when\r
+ <emphasis>git-init</emphasis> is run, but all of them are disabled by\r
+ default. To enable, the <literal>.sample</literal> suffix has to be\r
+ removed from the filename by renaming.\r
+ Read <xref linkend="githooks(5)"/> for more details about\r
+ each hook.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+index\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ The current index file for the repository. It is\r
+ usually not found in a bare repository.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+info\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Additional information about the repository is recorded\r
+ in this directory.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+info/refs\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ This file helps dumb transports discover what refs are\r
+ available in this repository. If the repository is\r
+ published for dumb transports, this file should be\r
+ regenerated by <emphasis>git-update-server-info</emphasis> every time a tag\r
+ or branch is created or modified. This is normally done\r
+ from the <literal>hooks/update</literal> hook, which is run by the\r
+ <emphasis>git-receive-pack</emphasis> command when you <emphasis>git-push</emphasis> into the\r
+ repository.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+info/grafts\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ This file records fake commit ancestry information, to\r
+ pretend the set of parents a commit has is different\r
+ from how the commit was actually created. One record\r
+ per line describes a commit and its fake parents by\r
+ listing their 40-byte hexadecimal object names separated\r
+ by a space and terminated by a newline.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+info/exclude\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ This file, by convention among Porcelains, stores the\r
+ exclude pattern list. <literal>.gitignore</literal> is the per-directory\r
+ ignore file. <emphasis>git-status</emphasis>, <emphasis>git-add</emphasis>, <emphasis>git-rm</emphasis> and\r
+ <emphasis>git-clean</emphasis> look at it but the core git commands do not look\r
+ at it. See also: <xref linkend="gitignore(5)"/>.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+remotes\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Stores shorthands to be used to give URL and default\r
+ refnames to interact with remote repository to\r
+ <emphasis>git-fetch</emphasis>, <emphasis>git-pull</emphasis> and <emphasis>git-push</emphasis> commands.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+logs\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Records of changes made to refs are stored in this\r
+ directory. See <xref linkend="git-update-ref(1)"/>\r
+ for more information.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+logs/refs/heads/<literal>name</literal>\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Records all changes made to the branch tip named <literal>name</literal>.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+logs/refs/tags/<literal>name</literal>\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ Records all changes made to the tag named <literal>name</literal>.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+<varlistentry>\r
+<term>\r
+shallow\r
+</term>\r
+<listitem>\r
+<simpara>\r
+ This is similar to <literal>info/grafts</literal> but is internally used\r
+ and maintained by shallow clone mechanism. See <literal>--depth</literal>\r
+ option to <xref linkend="git-clone(1)"/> and <xref linkend="git-fetch(1)"/>.\r
+</simpara>\r
+</listitem>\r
+</varlistentry>\r
+</variablelist>\r
+</simplesect>\r
+<simplesect id="_see_also">\r
+<title>SEE ALSO</title>\r
+<simpara><xref linkend="git-init(1)"/>,\r
+<xref linkend="git-clone(1)"/>,\r
+<xref linkend="git-fetch(1)"/>,\r
+<xref linkend="git-pack-refs(1)"/>,\r
+<xref linkend="git-gc(1)"/>,\r
+<xref linkend="git-checkout(1)"/>,\r
+<xref linkend="gitglossary(7)"/>,\r
+<ulink url="user-manual.html">The Git User’s Manual</ulink></simpara>\r
+</simplesect>\r
+<simplesect id="_git">\r
+<title>GIT</title>\r
+<simpara>Part of the <xref linkend="git(1)"/> suite.</simpara>\r
+</simplesect>\r
+</article>\r