Merge branch 'jc/numstat'

[git.git] / Documentation / repository-layout.txt

diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt
index 1f19bf86dd1dd031ac45b536905c092f550ef9f0..e20fb7e74c22390e810a392f2625a3ba6b325477 100644 (file)
--- a/Documentation/repository-layout.txt
+++ b/Documentation/repository-layout.txt
@@ -52,9 +52,20 @@ objects/info/packs::
        by default.
 
 objects/info/alternates::
-       This file records absolute filesystem paths of alternate
-       object stores that this object store borrows objects
-       from, one pathname per line.
+       This file records paths to alternate object stores that
+       this object store borrows objects from, one pathname per
+       line. Note that not only native Git tools use it locally,
+       but the HTTP fetcher also tries to use it remotely; this
+       will usually work if you have relative paths (relative
+       to the object database, not to the repository!) in your
+       alternates file, but it will not work if you use absolute
+       paths unless the absolute path in filesystem and web URL
+       is the same. See also 'objects/info/http-alternates'.
+
+objects/info/http-alternates::
+       This file records URLs to alternate object stores that
+       this object store borrows objects from, to be used when
+       the repository is fetched over HTTP.
 
 refs::
        References are stored in subdirectories of this
@@ -70,12 +81,16 @@ refs/tags/`name`::
        object, or a tag object that points at a commit object).
 
 HEAD::
-       A symlink of the form `refs/heads/'name'` to point at
-       the current branch, if exists.  It does not mean much if
-       the repository is not associated with any working tree
+       A symref (see glossary) to the `refs/heads/` namespace
+       describing the currently active branch.  It does not mean
+       much if the repository is not associated with any working tree
        (i.e. a 'bare' repository), but a valid git repository
-       *must* have such a symlink here.  It is legal if the
-       named branch 'name' does not (yet) exist.
+       *must* have the HEAD file; some porcelains may use it to
+       guess the designated "default" branch of the repository
+       (usually 'master').  It is legal if the named branch
+       'name' does not (yet) exist.  In some legacy setups, it is
+       a symbolic link instead of a symref that points at the current
+       branch.
 
 branches::
        A slightly deprecated way to store shorthands to be used
@@ -89,6 +104,8 @@ hooks::
        commands.  A handful of sample hooks are installed when
        `git init-db` is run, but all of them are disabled by
        default.  To enable, they need to be made executable.
+       Read link:hooks.html[hooks] for more details about
+       each hook.
 
 index::
        The current index file for the repository.  It is
@@ -118,11 +135,24 @@ info/grafts::
 
 info/exclude::
        This file, by convention among Porcelains, stores the
-       exclude pattern list.  `git status` looks at it, but
-       otherwise it is not looked at by any of the core git
-       commands.
+       exclude pattern list. `.gitignore` is the per-directory
+       ignore file.  `git status`, `git add`, `git rm` and `git
+       clean` look at it but the core git commands do not look
+       at it.  See also: gitlink:git-ls-files[1] `--exclude-from`
+       and `--exclude-per-directory`.
 
 remotes::
        Stores shorthands to be used to give URL and default
        refnames to interact with remote repository to `git
        fetch`, `git pull` and `git push` commands.
+
+logs::
+       Records of changes made to refs are stored in this
+       directory.  See the documentation on git-update-ref
+       for more information.
+
+logs/refs/heads/`name`::
+       Records all changes made to the branch tip named `name`.
+
+logs/refs/tags/`name`::
+       Records all changes made to the tag named `name`.