diff options
Diffstat (limited to 'Documentation/gitrepository-layout.txt')
| -rw-r--r-- | Documentation/gitrepository-layout.txt | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/Documentation/gitrepository-layout.txt b/Documentation/gitrepository-layout.txt new file mode 100644 index 0000000000..577ee844e0 --- /dev/null +++ b/Documentation/gitrepository-layout.txt @@ -0,0 +1,292 @@ +gitrepository-layout(5) +======================= + +NAME +---- +gitrepository-layout - Git Repository Layout + +SYNOPSIS +-------- +$GIT_DIR/* + +DESCRIPTION +----------- + +A Git repository comes in two different flavours: + + * a `.git` directory at the root of the working tree; + + * a `<project>.git` directory that is a 'bare' repository + (i.e. without its own working tree), that is typically used for + exchanging histories with others by pushing into it and fetching + from it. + +*Note*: Also you can have a plain text file `.git` at the root of +your working tree, containing `gitdir: <path>` to point at the real +directory that has the repository. This mechanism is often used for +a working tree of a submodule checkout, to allow you in the +containing superproject to `git checkout` a branch that does not +have the submodule. The `checkout` has to remove the entire +submodule working tree, without losing the submodule repository. + +These things may exist in a Git 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 a few ways to violate it. ++ +. You could have an incomplete but locally usable repository +by creating a shallow clone. See linkgit:git-clone[1]. +. You could be using the `objects/info/alternates` or +`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow' +objects from other object stores. A repository with this kind +of incomplete 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 object stores it +borrows from. ++ +This directory is ignored if $GIT_COMMON_DIR is set and +"$GIT_COMMON_DIR/objects" will be used instead. + +objects/[0-9a-f][0-9a-f]:: + A newly created object is stored in its own file. + The objects are splayed over 256 subdirectories using + the first two characters of the sha1 object name to + keep the number of directory entries in `objects` + itself to a manageable number. Objects found + here are often called 'unpacked' (or 'loose') 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 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 + directory. The 'git prune' command knows to preserve + objects reachable from refs found in this directory and + its subdirectories. This directory is ignored if $GIT_COMMON_DIR + is set and "$GIT_COMMON_DIR/refs" will be used instead. + +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). + +refs/remotes/`name`:: + records tip-of-the-tree commit objects of branches copied + from a remote repository. + +refs/replace/`<obj-sha1>`:: + records the SHA-1 of the object that replaces `<obj-sha1>`. + This is similar to info/grafts and is internally used and + maintained by linkgit:git-replace[1]. Such refs can be exchanged + between repositories while grafts are not. + +packed-refs:: + records the same information as refs/heads/, refs/tags/, + and friends record in a more efficient way. See + linkgit:git-pack-refs[1]. This file is ignored if $GIT_COMMON_DIR + is set and "$GIT_COMMON_DIR/packed-refs" will be used instead. + +HEAD:: + 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 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. ++ +HEAD can also record a specific commit directly, instead of +being a symref to point at the current branch. Such a state +is often called 'detached HEAD.' See linkgit:git-checkout[1] +for details. + +config:: + Repository specific configuration file. This file is ignored + if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be + used instead. + +branches:: + A slightly deprecated way to store shorthands to be used + to specify a URL to 'git fetch', 'git pull' and 'git push'. + A file can be stored as `branches/<name>` and then + 'name' can be given to these commands in place of + 'repository' argument. See the REMOTES section in + linkgit:git-fetch[1] for details. This mechanism is legacy + and not likely to be found in modern repositories. This + directory is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/branches" will be used instead. + + +hooks:: + Hooks are customization scripts used by various Git + commands. A handful of sample hooks are installed when + 'git init' is run, but all of them are disabled by + default. To enable, the `.sample` suffix has to be + removed from the filename by renaming. + Read linkgit:githooks[5] for more details about + each hook. This directory is ignored if $GIT_COMMON_DIR is set + and "$GIT_COMMON_DIR/hooks" will be used instead. + + +index:: + The current index file for the repository. It is + usually not found in a bare repository. + +sharedindex.<SHA-1>:: + The shared index part, to be referenced by $GIT_DIR/index and + other temporary index files. Only valid in split index mode. + +info:: + Additional information about the repository is recorded + in this directory. This directory is ignored if $GIT_COMMON_DIR + is set and "$GIT_COMMON_DIR/index" will be used instead. + +info/refs:: + This file helps dumb transports discover what refs are + available in this repository. If the repository is + published for dumb transports, this file should be + regenerated by 'git update-server-info' every time a tag + or branch is created or modified. This is normally done + from the `hooks/update` hook, which is run by the + 'git-receive-pack' command when you 'git push' into the + repository. + +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. ++ +Note that the grafts mechanism is outdated and can lead to problems +transferring objects between repositories; see linkgit:git-replace[1] +for a more flexible and robust system to do the same thing. + +info/exclude:: + This file, by convention among Porcelains, stores the + 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: linkgit:gitignore[5]. + +info/sparse-checkout:: + This file stores sparse checkout patterns. + See also: linkgit:git-read-tree[1]. + +remotes:: + Stores shorthands for URL and default refnames for use + when interacting with remote repositories via 'git fetch', + 'git pull' and 'git push' commands. See the REMOTES section + in linkgit:git-fetch[1] for details. This mechanism is legacy + and not likely to be found in modern repositories. This + directory is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/remotes" will be used instead. + +logs:: + Records of changes made to refs are stored in this directory. + See linkgit:git-update-ref[1] for more information. This + directory is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/logs" will be used instead. + +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`. + +shallow:: + This is similar to `info/grafts` but is internally used + and maintained by shallow clone mechanism. See `--depth` + option to linkgit:git-clone[1] and linkgit:git-fetch[1]. This + file is ignored if $GIT_COMMON_DIR is set and + "$GIT_COMMON_DIR/shallow" will be used instead. + +commondir:: + If this file exists, $GIT_COMMON_DIR (see linkgit:git[1]) will + be set to the path specified in this file if it is not + explicitly set. If the specified path is relative, it is + relative to $GIT_DIR. The repository with commondir is + incomplete without the repository pointed by "commondir". + +modules:: + Contains the git-repositories of the submodules. + +worktrees:: + Contains administrative data for linked + working trees. Each subdirectory contains the working tree-related + part of a linked working tree. This directory is ignored if + $GIT_COMMON_DIR is set, in which case + "$GIT_COMMON_DIR/worktrees" will be used instead. + +worktrees/<id>/gitdir:: + A text file containing the absolute path back to the .git file + that points to here. This is used to check if the linked + repository has been manually removed and there is no need to + keep this directory any more. The mtime of this file should be + updated every time the linked repository is accessed. + +worktrees/<id>/locked:: + If this file exists, the linked working tree may be on a + portable device and not available. The presence of this file + prevents `worktrees/<id>` from being pruned either automatically + or manually by `git worktree prune`. The file may contain a string + explaining why the repository is locked. + +worktrees/<id>/link:: + If this file exists, it is a hard link to the linked .git + file. It is used to detect if the linked repository is + manually removed. + +SEE ALSO +-------- +linkgit:git-init[1], +linkgit:git-clone[1], +linkgit:git-fetch[1], +linkgit:git-pack-refs[1], +linkgit:git-gc[1], +linkgit:git-checkout[1], +linkgit:gitglossary[7], +link:user-manual.html[The Git User's Manual] + +GIT +--- +Part of the linkgit:git[1] suite. |