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