Documentation: detached HEAD
[git/git.git] / Documentation / repository-layout.txt
1 git repository layout
2 =====================
3
4 You may find these things in your git repository (`.git`
5 directory for a repository associated with your working tree, or
6 `'project'.git` directory for a public 'bare' repository).
7
8 objects::
9 Object store associated with this repository. Usually
10 an object store is self sufficient (i.e. all the objects
11 that are referred to by an object found in it are also
12 found in it), but there are couple of ways to violate
13 it.
14 +
15 . You could populate the repository by running a commit walker
16 without `-a` option. Depending on which options are given, you
17 could have only commit objects without associated blobs and
18 trees this way, for example. A repository with this kind of
19 incomplete object store is not suitable to be published to the
20 outside world but sometimes useful for private repository.
21 . You can be using `objects/info/alternates` mechanism, or
22 `$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'
23 objects from other object stores. A repository with this kind
24 of incomplete object store is not suitable to be published for
25 use with dumb transports but otherwise is OK as long as
26 `objects/info/alternates` points at the right object stores
27 it borrows from.
28
29 objects/[0-9a-f][0-9a-f]::
30 Traditionally, each object is stored in its own file.
31 They are split into 256 subdirectories using the first
32 two letters from its object name to keep the number of
33 directory entries `objects` directory itself needs to
34 hold. Objects found here are often called 'unpacked'
35 objects.
36
37 objects/pack::
38 Packs (files that store many object in compressed form,
39 along with index files to allow them to be randomly
40 accessed) are found in this directory.
41
42 objects/info::
43 Additional information about the object store is
44 recorded in this directory.
45
46 objects/info/packs::
47 This file is to help dumb transports discover what packs
48 are available in this object store. Whenever a pack is
49 added or removed, `git update-server-info` should be run
50 to keep this file up-to-date if the repository is
51 published for dumb transports. `git repack` does this
52 by default.
53
54 objects/info/alternates::
55 This file records paths to alternate object stores that
56 this object store borrows objects from, one pathname per
57 line. Note that not only native Git tools use it locally,
58 but the HTTP fetcher also tries to use it remotely; this
59 will usually work if you have relative paths (relative
60 to the object database, not to the repository!) in your
61 alternates file, but it will not work if you use absolute
62 paths unless the absolute path in filesystem and web URL
63 is the same. See also 'objects/info/http-alternates'.
64
65 objects/info/http-alternates::
66 This file records URLs to alternate object stores that
67 this object store borrows objects from, to be used when
68 the repository is fetched over HTTP.
69
70 refs::
71 References are stored in subdirectories of this
72 directory. The `git prune` command knows to keep
73 objects reachable from refs found in this directory and
74 its subdirectories.
75
76 refs/heads/`name`::
77 records tip-of-the-tree commit objects of branch `name`
78
79 refs/tags/`name`::
80 records any object name (not necessarily a commit
81 object, or a tag object that points at a commit object).
82
83 HEAD::
84 A symref (see glossary) to the `refs/heads/` namespace
85 describing the currently active branch. It does not mean
86 much if the repository is not associated with any working tree
87 (i.e. a 'bare' repository), but a valid git repository
88 *must* have the HEAD file; some porcelains may use it to
89 guess the designated "default" branch of the repository
90 (usually 'master'). It is legal if the named branch
91 'name' does not (yet) exist. In some legacy setups, it is
92 a symbolic link instead of a symref that points at the current
93 branch.
94 +
95 HEAD can also record a specific commit directly, instead of
96 being a symref to point at the current branch. Such a state
97 is often called 'detached HEAD', and almost all commands work
98 identically as normal. See gitlink:git-checkout[1] for
99 details.
100
101 branches::
102 A slightly deprecated way to store shorthands to be used
103 to specify URL to `git fetch`, `git pull` and `git push`
104 commands is to store a file in `branches/'name'` and
105 give 'name' to these commands in place of 'repository'
106 argument.
107
108 hooks::
109 Hooks are customization scripts used by various git
110 commands. A handful of sample hooks are installed when
111 `git init` is run, but all of them are disabled by
112 default. To enable, they need to be made executable.
113 Read link:hooks.html[hooks] for more details about
114 each hook.
115
116 index::
117 The current index file for the repository. It is
118 usually not found in a bare repository.
119
120 info::
121 Additional information about the repository is recorded
122 in this directory.
123
124 info/refs::
125 This file is to help dumb transports to discover what
126 refs are available in this repository. Whenever you
127 create/delete a new branch or a new tag, `git
128 update-server-info` should be run to keep this file
129 up-to-date if the repository is published for dumb
130 transports. The `git-receive-pack` command, which is
131 run on a remote repository when you `git push` into it,
132 runs `hooks/update` hook to help you achieve this.
133
134 info/grafts::
135 This file records fake commit ancestry information, to
136 pretend the set of parents a commit has is different
137 from how the commit was actually created. One record
138 per line describes a commit and its fake parents by
139 listing their 40-byte hexadecimal object names separated
140 by a space and terminated by a newline.
141
142 info/exclude::
143 This file, by convention among Porcelains, stores the
144 exclude pattern list. `.gitignore` is the per-directory
145 ignore file. `git status`, `git add`, `git rm` and `git
146 clean` look at it but the core git commands do not look
147 at it. See also: gitlink:git-ls-files[1] `--exclude-from`
148 and `--exclude-per-directory`.
149
150 remotes::
151 Stores shorthands to be used to give URL and default
152 refnames to interact with remote repository to `git
153 fetch`, `git pull` and `git push` commands.
154
155 logs::
156 Records of changes made to refs are stored in this
157 directory. See the documentation on git-update-ref
158 for more information.
159
160 logs/refs/heads/`name`::
161 Records all changes made to the branch tip named `name`.
162
163 logs/refs/tags/`name`::
164 Records all changes made to the tag named `name`.