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