Add repository-layout document.

... and link to it from both the main index and the tutorial.

Signed-off-by: Junio C Hamano <junkio@cox.net>

4 files changed, 148 insertions, 14 deletions

diff --git a/Documentation/Makefile b/Documentation/Makefile
index e19c86f19c..afdecc1a7f 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -3,7 +3,11 @@ MAN7_TXT=git.txt
 
 DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT))
 
-ARTICLES = tutorial cvs-migration diffcore howto-index
+ARTICLES = tutorial
+ARTICLES += cvs-migration
+ARTICLES += diffcore
+ARTICLES += howto-index
+ARTICLES += repository-layout
 # with their own formatting rules.
 SP_ARTICLES = glossary howto/revert-branch-rebase
 
diff --git a/Documentation/git.txt b/Documentation/git.txt
index dba90358cd..2f8a6479e1 100644
--- a/Documentation/git.txt
+++ b/Documentation/git.txt
@@ -412,24 +412,13 @@ HEAD::
 
 File/Directory Structure
 ------------------------
-The git-core manipulates the following areas in the directory:
 
- .git/	       The base (overridden with $GIT_DIR)
-   objects/    The object base (overridden with $GIT_OBJECT_DIRECTORY)
-     ??/       'First 2 chars of object' directories.
-     pack/     Packed archives.
-
-   refs/       Directories containing symbolic names for objects
-	       (each file contains the hex SHA1 + newline)
-     heads/    Commits which are heads of various sorts
-     tags/     Tags, by the tag name (or some local renaming of it)
-     */        Any other subdirectory of refs/ can be used to store
-	       files similar to what are under refs/heads/.
-   HEAD        Symlink to refs/heads/<current-branch-name>
+Please see link:repository-layout.html[repository layout] document.
 
 Higher level SCMs may provide and manage additional information in the
 GIT_DIR.
 
+
 Terminology
 -----------
 Please see link:glossary.html[glossary] document.
diff --git a/Documentation/repository-layout.txt b/Documentation/repository-layout.txt
new file mode 100644
index 0000000000..297a47bdf3
--- /dev/null
+++ b/Documentation/repository-layout.txt
@@ -0,0 +1,136 @@
+GIT repository layout
+=====================
+v0.99.5, Sep 2005
+
+You may find these things in your git repository (`.git`
+directory for a repository associated with your working tree, or
+`'project'.git` directory for a public 'naked' repository).
+
+objects::
+	Object store associated with this repository.  Usually
+	an object store is self sufficient (i.e. all the objects
+	that are referred to by an object found in it are also
+	found in it), but there are couple of ways to violate
+	it.
++
+. You could populate the repository by running a commit walker
+without `-a` option.  Depending on which options are given, you
+could have only commit objects without associated blobs and
+trees this way, for example.  A repository with this kind of
+incomplete object store is not suitable to be published to the
+outside world but sometimes useful for private repository.
+. You can be using `objects/info/alternates` mechanism, or
+`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'
+objects from other object stores.  A repository with this kind
+of incompete object store is not suitable to be published for
+use with dumb transports but otherwise is OK as long as
+`objects/info/alternates` points at the right object stores
+it borrows from.
+
+objects/[0-9a-f][0-9a-f]::
+	Traditionally, each object is stored in its own file.
+	They are split into 256 subdirectories using the first
+	two letters from its object name to keep the number of
+	directory entries `objects` directory itself needs to
+	hold.  Objects found here are often called 'unpacked'
+	objects.
+
+objects/pack::
+	Packs (files that store many object in compressed form,
+	along with index files to allow them to be randomly
+	accessed) are found in this directory.
+
+objects/info::
+	Additional information about the object store is
+	recorded in this directory.
+
+objects/info/packs::
+	This file is to help dumb transports discover what packs
+	are available in this object store.  Whenever a pack is
+	added or removed, `git update-server-info` should be run
+	to keep this file up-to-date if the repository is
+	published for dumb transports.  `git repack` does this
+	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.
+
+refs::
+	References are stored in subdirectories of this
+	directory.  The `git prune` command knows to keep
+	objects reachable from refs found in this directory and
+	its subdirectories.
+
+refs/heads/`name`::
+	records tip-of-the-tree commit objects of branch `name`
+
+refs/tags/`name`::
+	records any object name (not necessarily a commit
+	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
+	(i.e. 'naked' repository), but a valid git repository
+	*must* have such a symlink here.  It is legal if the
+	named branch 'name' does not (yet) exist.
+
+branches::
+	A slightly deprecated way to store shorthands to be used
+	to specify URL to `git fetch`, `git pull` and `git push`
+	commands is to store a file in `branches/'name'` and
+	give 'name' to these commands in place of 'repository'
+	argument.
+
+hooks::
+	Hooks are customization scripts used by various git
+	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.
+
+index::
+	The current index file for the repository.  It is
+	usually not found in a naked repository.
+
+info::
+	Additional information about the repository is recorded
+	in this directory.
+
+info/refs::
+	This file is to help dumb transports to discover what
+	refs are available in this repository.  Whenever you
+	create/delete a new branch or a new tag, `git
+	update-server-info` should be run to keep this file
+	up-to-date if the repository is published for dumb
+	transports.  The `git-receive-pack` command, which is
+	run on a remote repository when you `git push` into it,
+	runs `hooks/update` hook to help you achive this.
+
+info/grafts::
+	This file records fake commit ancestry information, to
+	pretend the set of parents a commit has is different
+	from how the commit was actually created.  One record
+	per line describes a commit and its fake parents by
+	listing their 40-byte hexadecimal object names separated
+	by a space and terminated by a newline.
+
+info/rev-cache::
+	No higher-level tool currently takes advantage of this
+	file, but it is generated when `git update-server-info`
+	is run.  It records the commit ancestry information of
+	the commits in this repository in a concise binary
+	format, and can be read with `git-show-rev-cache`.
+
+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.
+
+remotes::
+	Stoers shorthands to be used to give URL and default
+	refnames to interact with remote repository to `git
+	fetch`, `git pull` and `git push` commands.
diff --git a/Documentation/tutorial.txt b/Documentation/tutorial.txt
index 1ed8038f79..04354a37b9 100644
--- a/Documentation/tutorial.txt
+++ b/Documentation/tutorial.txt
@@ -93,6 +93,11 @@ expect to see a number of 41-byte files containing these
 references in these `refs` subdirectories when you actually start
 populating your tree.
 
+[NOTE]
+An advanced user may want to take a look at the
+link:repository-layout.html[repository layout] document
+after finishing this tutorial.
+
 You have now created your first git repository. Of course, since it's
 empty, that's not very useful, so let's start populating it with data.