1GITREPOSITORY-LAYOU(5)            Git Manual            GITREPOSITORY-LAYOU(5)
2
3
4

NAME

6       gitrepository-layout - Git Repository Layout
7

SYNOPSIS

9       $GIT_DIR/*
10

DESCRIPTION

12       A Git repository comes in two different flavours:
13
14       ·   a .git directory at the root of the working tree;
15
16       ·   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
20       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
28       These things may exist in a Git repository.
29
30       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
36            1. You could have an incomplete but locally usable repository by
37               creating a shallow clone. See git-clone(1).
38
39            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
47               This directory is ignored if $GIT_COMMON_DIR is set and
48               "$GIT_COMMON_DIR/objects" will be used instead.
49
50       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
57       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
62       objects/info
63           Additional information about the object store is recorded in this
64           directory.
65
66       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
73       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
83       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
88       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
95       refs/heads/name
96           records tip-of-the-tree commit objects of branch name
97
98       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
102       refs/remotes/name
103           records tip-of-the-tree commit objects of branches copied from a
104           remote repository.
105
106       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
112       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
118       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
128           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
132       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
137       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
142       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
152       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
161       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
166       index
167           The current index file for the repository. It is usually not found
168           in a bare repository.
169
170       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
174       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
179       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
188       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
195           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
199       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
205       info/attributes
206           Defines which attributes to assign to a path, similar to
207           per-directory .gitattributes files. See also: gitattributes(5).
208
209       info/sparse-checkout
210           This file stores sparse checkout patterns. See also: git-read-
211           tree(1).
212
213       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
221       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
227       logs/refs/heads/name
228           Records all changes made to the branch tip named name.
229
230       logs/refs/tags/name
231           Records all changes made to the tag named name.
232
233       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
239       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
246       modules
247           Contains the git-repositories of the submodules.
248
249       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
255       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
262       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
269       worktrees/<id>/config.worktree
270           Working directory specific configuration file.
271

GIT REPOSITORY FORMAT VERSIONS

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
281       Because of this rule, version bumps should be kept to an absolute
282       minimum. Instead, we generally prefer these strategies:
283
284       ·   bumping format version numbers of individual data files (e.g.,
285           index, packfiles, etc). This restricts the incompatibilities only
286           to those files.
287
288       ·   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
293       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
298       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
303       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
311       The currently defined format versions are:
312
313   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
319   Version 1
320       This format is identical to version 0, with the following exceptions:
321
322        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
327        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
332       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
337       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
341       The defined extensions are:
342
343       noop
344           This extension does not change git’s behavior at all. It is useful
345           only for testing format-1 compatibility.
346
347       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
352       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
360           The value of this key is the name of the promisor remote.
361
362       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

SEE ALSO

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

GIT

374       Part of the git(1) suite
375

NOTES

377        1. The Git User’s Manual
378           file:///usr/share/doc/git/user-manual.html
379
380
381
382Git 2.21.0                        02/24/2019            GITREPOSITORY-LAYOU(5)
Impressum