1GITREPOSITORY-LAYOU(5) Git Manual GITREPOSITORY-LAYOU(5)
2
6 gitrepository-layout - Git Repository Layout
7
9 $GIT_DIR/*
10
12 A Git repository comes in two different flavours:
13 · a .git directory at the root of the working tree;
15 · a <project>.git directory that is a bare repository (i.e. without
17 its own working tree), that is typically used for exchanging
18 histories with others by pushing into it and fetching from it.
19 Note: Also you can have a plain text file .git at the root of your
21 working tree, containing gitdir: <path> to point at the real directory
22 that has the repository. This mechanism is often used for a working
23 tree of a submodule checkout, to allow you in the containing
24 superproject to git checkout a branch that does not have the submodule.
25 The checkout has to remove the entire submodule working tree, without
26 losing the submodule repository.
27 These things may exist in a Git repository.
29 objects
31 Object store associated with this repository. Usually an object
32 store is self sufficient (i.e. all the objects that are referred to
33 by an object found in it are also found in it), but there are a few
34 ways to violate it.
35 1. You could have an incomplete but locally usable repository by
37 creating a shallow clone. See git-clone(1).
38 2. You could be using the objects/info/alternates or
40 $GIT_ALTERNATE_OBJECT_DIRECTORIES mechanisms to borrow objects
41 from other object stores. A repository with this kind of
42 incomplete object store is not suitable to be published for use
43 with dumb transports but otherwise is OK as long as
44 objects/info/alternates points at the object stores it borrows
45 from.
46 This directory is ignored if $GIT_COMMON_DIR is set and
48 "$GIT_COMMON_DIR/objects" will be used instead.
49 objects/[0-9a-f][0-9a-f]
51 A newly created object is stored in its own file. The objects are
52 splayed over 256 subdirectories using the first two characters of
53 the sha1 object name to keep the number of directory entries in
54 objects itself to a manageable number. Objects found here are often
55 called unpacked (or loose) objects.
56 objects/pack
58 Packs (files that store many object in compressed form, along with
59 index files to allow them to be randomly accessed) are found in
60 this directory.
61 objects/info
63 Additional information about the object store is recorded in this
64 directory.
65 objects/info/packs
67 This file is to help dumb transports discover what packs are
68 available in this object store. Whenever a pack is added or
69 removed, git update-server-info should be run to keep this file up
70 to date if the repository is published for dumb transports. git
71 repack does this by default.
72 objects/info/alternates
74 This file records paths to alternate object stores that this object
75 store borrows objects from, one pathname per line. Note that not
76 only native Git tools use it locally, but the HTTP fetcher also
77 tries to use it remotely; this will usually work if you have
78 relative paths (relative to the object database, not to the
79 repository!) in your alternates file, but it will not work if you
80 use absolute paths unless the absolute path in filesystem and web
81 URL is the same. See also objects/info/http-alternates.
82 objects/info/http-alternates
84 This file records URLs to alternate object stores that this object
85 store borrows objects from, to be used when the repository is
86 fetched over HTTP.
87 refs
89 References are stored in subdirectories of this directory. The git
90 prune command knows to preserve objects reachable from refs found
91 in this directory and its subdirectories. This directory is ignored
92 (except refs/bisect and refs/worktree) if $GIT_COMMON_DIR is set
93 and "$GIT_COMMON_DIR/refs" will be used instead.
94 refs/heads/name
96 records tip-of-the-tree commit objects of branch name
97 refs/tags/name
99 records any object name (not necessarily a commit object, or a tag
100 object that points at a commit object).
101 refs/remotes/name
103 records tip-of-the-tree commit objects of branches copied from a
104 remote repository.
105 refs/replace/<obj-sha1>
107 records the SHA-1 of the object that replaces <obj-sha1>. This is
108 similar to info/grafts and is internally used and maintained by
109 git-replace(1). Such refs can be exchanged between repositories
110 while grafts are not.
111 packed-refs
113 records the same information as refs/heads/, refs/tags/, and
114 friends record in a more efficient way. See git-pack-refs(1). This
115 file is ignored if $GIT_COMMON_DIR is set and
116 "$GIT_COMMON_DIR/packed-refs" will be used instead.
117 HEAD
119 A symref (see glossary) to the refs/heads/ namespace describing the
120 currently active branch. It does not mean much if the repository is
121 not associated with any working tree (i.e. a bare repository), but
122 a valid Git repository must have the HEAD file; some porcelains may
123 use it to guess the designated "default" branch of the repository
124 (usually master). It is legal if the named branch name does not
125 (yet) exist. In some legacy setups, it is a symbolic link instead
126 of a symref that points at the current branch.
127 HEAD can also record a specific commit directly, instead of being a
129 symref to point at the current branch. Such a state is often called
130 detached HEAD. See git-checkout(1) for details.
131 config
133 Repository specific configuration file. This file is ignored if
134 $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be used
135 instead.
136 config.worktree
138 Working directory specific configuration file for the main working
139 directory in multiple working directory setup (see git-
140 worktree(1)).
141 branches
143 A slightly deprecated way to store shorthands to be used to specify
144 a URL to git fetch, git pull and git push. A file can be stored as
145 branches/<name> and then name can be given to these commands in
146 place of repository argument. See the REMOTES section in git-
147 fetch(1) for details. This mechanism is legacy and not likely to be
148 found in modern repositories. This directory is ignored if
149 $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/branches" will be used
150 instead.
151 hooks
153 Hooks are customization scripts used by various Git commands. A
154 handful of sample hooks are installed when git init is run, but all
155 of them are disabled by default. To enable, the .sample suffix has
156 to be removed from the filename by renaming. Read githooks(5) for
157 more details about each hook. This directory is ignored if
158 $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/hooks" will be used
159 instead.
160 common
162 When multiple working trees are used, most of files in $GIT_DIR are
163 per-worktree with a few known exceptions. All files under common
164 however will be shared between all working trees.
165 index
167 The current index file for the repository. It is usually not found
168 in a bare repository.
169 sharedindex.<SHA-1>
171 The shared index part, to be referenced by $GIT_DIR/index and other
172 temporary index files. Only valid in split index mode.
173 info
175 Additional information about the repository is recorded in this
176 directory. This directory is ignored if $GIT_COMMON_DIR is set and
177 "$GIT_COMMON_DIR/info" will be used instead.
178 info/refs
180 This file helps dumb transports discover what refs are available in
181 this repository. If the repository is published for dumb
182 transports, this file should be regenerated by git
183 update-server-info every time a tag or branch is created or
184 modified. This is normally done from the hooks/update hook, which
185 is run by the git-receive-pack command when you git push into the
186 repository.
187 info/grafts
189 This file records fake commit ancestry information, to pretend the
190 set of parents a commit has is different from how the commit was
191 actually created. One record per line describes a commit and its
192 fake parents by listing their 40-byte hexadecimal object names
193 separated by a space and terminated by a newline.
194 Note that the grafts mechanism is outdated and can lead to problems
196 transferring objects between repositories; see git-replace(1) for a
197 more flexible and robust system to do the same thing.
198 info/exclude
200 This file, by convention among Porcelains, stores the exclude
201 pattern list. .gitignore is the per-directory ignore file. git
202 status, git add, git rm and git clean look at it but the core Git
203 commands do not look at it. See also: gitignore(5).
204 info/attributes
206 Defines which attributes to assign to a path, similar to
207 per-directory .gitattributes files. See also: gitattributes(5).
208 info/sparse-checkout
210 This file stores sparse checkout patterns. See also: git-read-
211 tree(1).
212 remotes
214 Stores shorthands for URL and default refnames for use when
215 interacting with remote repositories via git fetch, git pull and
216 git push commands. See the REMOTES section in git-fetch(1) for
217 details. This mechanism is legacy and not likely to be found in
218 modern repositories. This directory is ignored if $GIT_COMMON_DIR
219 is set and "$GIT_COMMON_DIR/remotes" will be used instead.
220 logs
222 Records of changes made to refs are stored in this directory. See
223 git-update-ref(1) for more information. This directory is ignored
224 if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/logs" will be used
225 instead.
226 logs/refs/heads/name
228 Records all changes made to the branch tip named name.
229 logs/refs/tags/name
231 Records all changes made to the tag named name.
232 shallow
234 This is similar to info/grafts but is internally used and
235 maintained by shallow clone mechanism. See --depth option to git-
236 clone(1) and git-fetch(1). This file is ignored if $GIT_COMMON_DIR
237 is set and "$GIT_COMMON_DIR/shallow" will be used instead.
238 commondir
240 If this file exists, $GIT_COMMON_DIR (see git(1)) will be set to
241 the path specified in this file if it is not explicitly set. If the
242 specified path is relative, it is relative to $GIT_DIR. The
243 repository with commondir is incomplete without the repository
244 pointed by "commondir".
245 modules
247 Contains the git-repositories of the submodules.
248 worktrees
250 Contains administrative data for linked working trees. Each
251 subdirectory contains the working tree-related part of a linked
252 working tree. This directory is ignored if $GIT_COMMON_DIR is set,
253 in which case "$GIT_COMMON_DIR/worktrees" will be used instead.
254 worktrees/<id>/gitdir
256 A text file containing the absolute path back to the .git file that
257 points to here. This is used to check if the linked repository has
258 been manually removed and there is no need to keep this directory
259 any more. The mtime of this file should be updated every time the
260 linked repository is accessed.
261 worktrees/<id>/locked
263 If this file exists, the linked working tree may be on a portable
264 device and not available. The presence of this file prevents
265 worktrees/<id> from being pruned either automatically or manually
266 by git worktree prune. The file may contain a string explaining why
267 the repository is locked.
268 worktrees/<id>/config.worktree
270 Working directory specific configuration file.
271
273 Every git repository is marked with a numeric version in the
274 core.repositoryformatversion key of its config file. This version
275 specifies the rules for operating on the on-disk repository data. An
276 implementation of git which does not understand a particular version
277 advertised by an on-disk repository MUST NOT operate on that
278 repository; doing so risks not only producing wrong results, but
279 actually losing data.
280 Because of this rule, version bumps should be kept to an absolute
282 minimum. Instead, we generally prefer these strategies:
283 · bumping format version numbers of individual data files (e.g.,
285 index, packfiles, etc). This restricts the incompatibilities only
286 to those files.
287 · introducing new data that gracefully degrades when used by older
289 clients (e.g., pack bitmap files are ignored by older clients,
290 which simply do not take advantage of the optimization they
291 provide).
292 A whole-repository format version bump should only be part of a change
294 that cannot be independently versioned. For instance, if one were to
295 change the reachability rules for objects, or the rules for locking
296 refs, that would require a bump of the repository format version.
297 Note that this applies only to accessing the repository’s disk contents
299 directly. An older client which understands only format 0 may still
300 connect via git:// to a repository using format 1, as long as the
301 server process understands format 1.
302 The preferred strategy for rolling out a version bump (whether whole
304 repository or for a single file) is to teach git to read the new
305 format, and allow writing the new format with a config switch or
306 command line option (for experimentation or for those who do not care
307 about backwards compatibility with older gits). Then after a long
308 period to allow the reading capability to become common, we may switch
309 to writing the new format by default.
310 The currently defined format versions are:
312 Version 0
314 This is the format defined by the initial version of git, including but
315 not limited to the format of the repository directory, the repository
316 configuration file, and the object and ref storage. Specifying the
317 complete behavior of git is beyond the scope of this document.
318 Version 1
320 This format is identical to version 0, with the following exceptions:
321 1. When reading the core.repositoryformatversion variable, a git
323 implementation which supports version 1 MUST also read any
324 configuration keys found in the extensions section of the
325 configuration file.
326 2. If a version-1 repository specifies any extensions.* keys that the
328 running git has not implemented, the operation MUST NOT proceed.
329 Similarly, if the value of any known key is not understood by the
330 implementation, the operation MUST NOT proceed.
331 Note that if no extensions are specified in the config file, then
333 core.repositoryformatversion SHOULD be set to 0 (setting it to 1
334 provides no benefit, and makes the repository incompatible with older
335 implementations of git).
336 This document will serve as the master list for extensions. Any
338 implementation wishing to define a new extension should make a note of
339 it here, in order to claim the name.
340 The defined extensions are:
342 noop
344 This extension does not change git’s behavior at all. It is useful
345 only for testing format-1 compatibility.
346 preciousObjects
348 When the config key extensions.preciousObjects is set to true,
349 objects in the repository MUST NOT be deleted (e.g., by git-prune
350 or git repack -d).
351 partialclone
353 When the config key extensions.partialclone is set, it indicates
354 that the repo was created with a partial clone (or later performed
355 a partial fetch) and that the remote may have omitted sending
356 certain unwanted objects. Such a remote is called a "promisor
357 remote" and it promises that all such omitted objects can be
358 fetched from it in the future.
359 The value of this key is the name of the promisor remote.
361 worktreeConfig
363 If set, by default "git config" reads from both "config" and
364 "config.worktree" file from GIT_DIR in that order. In multiple
365 working directory mode, "config" file is shared while
366 "config.worktree" is per-working directory (i.e., it’s in
367 GIT_COMMON_DIR/worktrees/<id>/config.worktree)
368
370 git-init(1), git-clone(1), git-fetch(1), git-pack-refs(1), git-gc(1),
371 git-checkout(1), gitglossary(7), The Git User’s Manual[1]
372
374 Part of the git(1) suite
375
377 1. The Git User’s Manual
378 file:///usr/share/doc/git/user-manual.html
379Git 2.21.0 02/24/2019 GITREPOSITORY-LAYOU(5)