diff options
| -rw-r--r-- | Documentation/Makefile | 6 | ||||
| -rw-r--r-- | Documentation/git.txt | 15 | ||||
| -rw-r--r-- | Documentation/repository-layout.txt | 136 | ||||
| -rw-r--r-- | Documentation/tutorial.txt | 5 |
4 files changed, 148 insertions, 14 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index e19c86f19..afdecc1a7 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 dba90358c..2f8a6479e 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 000000000..297a47bdf --- /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 1ed8038f7..04354a37b 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. |