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 objects 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, refs/rewritten and refs/worktree) if
93           $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/refs" will be used
94           instead.
95
96       refs/heads/name
97           records tip-of-the-tree commit objects of branch name
98
99       refs/tags/name
100           records any object name (not necessarily a commit object, or a tag
101           object that points at a commit object).
102
103       refs/remotes/name
104           records tip-of-the-tree commit objects of branches copied from a
105           remote repository.
106
107       refs/replace/<obj-sha1>
108           records the SHA-1 of the object that replaces <obj-sha1>. This is
109           similar to info/grafts and is internally used and maintained by
110           git-replace(1). Such refs can be exchanged between repositories
111           while grafts are not.
112
113       packed-refs
114           records the same information as refs/heads/, refs/tags/, and
115           friends record in a more efficient way. See git-pack-refs(1). This
116           file is ignored if $GIT_COMMON_DIR is set and
117           "$GIT_COMMON_DIR/packed-refs" will be used instead.
118
119       HEAD
120           A symref (see glossary) to the refs/heads/ namespace describing the
121           currently active branch. It does not mean much if the repository is
122           not associated with any working tree (i.e. a bare repository), but
123           a valid Git repository must have the HEAD file; some porcelains may
124           use it to guess the designated "default" branch of the repository
125           (usually master). It is legal if the named branch name does not
126           (yet) exist. In some legacy setups, it is a symbolic link instead
127           of a symref that points at the current branch.
128
129           HEAD can also record a specific commit directly, instead of being a
130           symref to point at the current branch. Such a state is often called
131           detached HEAD.  See git-checkout(1) for details.
132
133       config
134           Repository specific configuration file. This file is ignored if
135           $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be used
136           instead.
137
138       config.worktree
139           Working directory specific configuration file for the main working
140           directory in multiple working directory setup (see git-
141           worktree(1)).
142
143       branches
144           A slightly deprecated way to store shorthands to be used to specify
145           a URL to git fetch, git pull and git push. A file can be stored as
146           branches/<name> and then name can be given to these commands in
147           place of repository argument. See the REMOTES section in git-
148           fetch(1) for details. This mechanism is legacy and not likely to be
149           found in modern repositories. This directory is ignored if
150           $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/branches" will be used
151           instead.
152
153       hooks
154           Hooks are customization scripts used by various Git commands. A
155           handful of sample hooks are installed when git init is run, but all
156           of them are disabled by default. To enable, the .sample suffix has
157           to be removed from the filename by renaming. Read githooks(5) for
158           more details about each hook. This directory is ignored if
159           $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/hooks" will be used
160           instead.
161
162       common
163           When multiple working trees are used, most of files in $GIT_DIR are
164           per-worktree with a few known exceptions. All files under common
165           however will be shared between all working trees.
166
167       index
168           The current index file for the repository. It is usually not found
169           in a bare repository.
170
171       sharedindex.<SHA-1>
172           The shared index part, to be referenced by $GIT_DIR/index and other
173           temporary index files. Only valid in split index mode.
174
175       info
176           Additional information about the repository is recorded in this
177           directory. This directory is ignored if $GIT_COMMON_DIR is set and
178           "$GIT_COMMON_DIR/info" will be used instead.
179
180       info/refs
181           This file helps dumb transports discover what refs are available in
182           this repository. If the repository is published for dumb
183           transports, this file should be regenerated by git
184           update-server-info every time a tag or branch is created or
185           modified. This is normally done from the hooks/update hook, which
186           is run by the git-receive-pack command when you git push into the
187           repository.
188
189       info/grafts
190           This file records fake commit ancestry information, to pretend the
191           set of parents a commit has is different from how the commit was
192           actually created. One record per line describes a commit and its
193           fake parents by listing their 40-byte hexadecimal object names
194           separated by a space and terminated by a newline.
195
196           Note that the grafts mechanism is outdated and can lead to problems
197           transferring objects between repositories; see git-replace(1) for a
198           more flexible and robust system to do the same thing.
199
200       info/exclude
201           This file, by convention among Porcelains, stores the exclude
202           pattern list.  .gitignore is the per-directory ignore file.  git
203           status, git add, git rm and git clean look at it but the core Git
204           commands do not look at it. See also: gitignore(5).
205
206       info/attributes
207           Defines which attributes to assign to a path, similar to
208           per-directory .gitattributes files. See also: gitattributes(5).
209
210       info/sparse-checkout
211           This file stores sparse checkout patterns. See also: git-read-
212           tree(1).
213
214       remotes
215           Stores shorthands for URL and default refnames for use when
216           interacting with remote repositories via git fetch, git pull and
217           git push commands. See the REMOTES section in git-fetch(1) for
218           details. This mechanism is legacy and not likely to be found in
219           modern repositories. This directory is ignored if $GIT_COMMON_DIR
220           is set and "$GIT_COMMON_DIR/remotes" will be used instead.
221
222       logs
223           Records of changes made to refs are stored in this directory. See
224           git-update-ref(1) for more information. This directory is ignored
225           (except logs/HEAD) if $GIT_COMMON_DIR is set and
226           "$GIT_COMMON_DIR/logs" will be used instead.
227
228       logs/refs/heads/name
229           Records all changes made to the branch tip named name.
230
231       logs/refs/tags/name
232           Records all changes made to the tag named name.
233
234       shallow
235           This is similar to info/grafts but is internally used and
236           maintained by shallow clone mechanism. See --depth option to git-
237           clone(1) and git-fetch(1). This file is ignored if $GIT_COMMON_DIR
238           is set and "$GIT_COMMON_DIR/shallow" will be used instead.
239
240       commondir
241           If this file exists, $GIT_COMMON_DIR (see git(1)) will be set to
242           the path specified in this file if it is not explicitly set. If the
243           specified path is relative, it is relative to $GIT_DIR. The
244           repository with commondir is incomplete without the repository
245           pointed by "commondir".
246
247       modules
248           Contains the git-repositories of the submodules.
249
250       worktrees
251           Contains administrative data for linked working trees. Each
252           subdirectory contains the working tree-related part of a linked
253           working tree. This directory is ignored if $GIT_COMMON_DIR is set,
254           in which case "$GIT_COMMON_DIR/worktrees" will be used instead.
255
256       worktrees/<id>/gitdir
257           A text file containing the absolute path back to the .git file that
258           points to here. This is used to check if the linked repository has
259           been manually removed and there is no need to keep this directory
260           any more. The mtime of this file should be updated every time the
261           linked repository is accessed.
262
263       worktrees/<id>/locked
264           If this file exists, the linked working tree may be on a portable
265           device and not available. The presence of this file prevents
266           worktrees/<id> from being pruned either automatically or manually
267           by git worktree prune. The file may contain a string explaining why
268           the repository is locked.
269
270       worktrees/<id>/config.worktree
271           Working directory specific configuration file.
272

GIT REPOSITORY FORMAT VERSIONS

274       Every git repository is marked with a numeric version in the
275       core.repositoryformatversion key of its config file. This version
276       specifies the rules for operating on the on-disk repository data. An
277       implementation of git which does not understand a particular version
278       advertised by an on-disk repository MUST NOT operate on that
279       repository; doing so risks not only producing wrong results, but
280       actually losing data.
281
282       Because of this rule, version bumps should be kept to an absolute
283       minimum. Instead, we generally prefer these strategies:
284
285       •   bumping format version numbers of individual data files (e.g.,
286           index, packfiles, etc). This restricts the incompatibilities only
287           to those files.
288
289       •   introducing new data that gracefully degrades when used by older
290           clients (e.g., pack bitmap files are ignored by older clients,
291           which simply do not take advantage of the optimization they
292           provide).
293
294       A whole-repository format version bump should only be part of a change
295       that cannot be independently versioned. For instance, if one were to
296       change the reachability rules for objects, or the rules for locking
297       refs, that would require a bump of the repository format version.
298
299       Note that this applies only to accessing the repository’s disk contents
300       directly. An older client which understands only format 0 may still
301       connect via git:// to a repository using format 1, as long as the
302       server process understands format 1.
303
304       The preferred strategy for rolling out a version bump (whether whole
305       repository or for a single file) is to teach git to read the new
306       format, and allow writing the new format with a config switch or
307       command line option (for experimentation or for those who do not care
308       about backwards compatibility with older gits). Then after a long
309       period to allow the reading capability to become common, we may switch
310       to writing the new format by default.
311
312       The currently defined format versions are:
313
314   Version 0
315       This is the format defined by the initial version of git, including but
316       not limited to the format of the repository directory, the repository
317       configuration file, and the object and ref storage. Specifying the
318       complete behavior of git is beyond the scope of this document.
319
320   Version 1
321       This format is identical to version 0, with the following exceptions:
322
323        1. When reading the core.repositoryformatversion variable, a git
324           implementation which supports version 1 MUST also read any
325           configuration keys found in the extensions section of the
326           configuration file.
327
328        2. If a version-1 repository specifies any extensions.*  keys that the
329           running git has not implemented, the operation MUST NOT proceed.
330           Similarly, if the value of any known key is not understood by the
331           implementation, the operation MUST NOT proceed.
332
333       Note that if no extensions are specified in the config file, then
334       core.repositoryformatversion SHOULD be set to 0 (setting it to 1
335       provides no benefit, and makes the repository incompatible with older
336       implementations of git).
337
338       This document will serve as the master list for extensions. Any
339       implementation wishing to define a new extension should make a note of
340       it here, in order to claim the name.
341
342       The defined extensions are:
343
344       noop
345           This extension does not change git’s behavior at all. It is useful
346           only for testing format-1 compatibility.
347
348       preciousObjects
349           When the config key extensions.preciousObjects is set to true,
350           objects in the repository MUST NOT be deleted (e.g., by git-prune
351           or git repack -d).
352
353       partialClone
354           When the config key extensions.partialClone is set, it indicates
355           that the repo was created with a partial clone (or later performed
356           a partial fetch) and that the remote may have omitted sending
357           certain unwanted objects. Such a remote is called a "promisor
358           remote" and it promises that all such omitted objects can be
359           fetched from it in the future.
360
361           The value of this key is the name of the promisor remote.
362
363       worktreeConfig
364           If set, by default "git config" reads from both "config" and
365           "config.worktree" file from GIT_DIR in that order. In multiple
366           working directory mode, "config" file is shared while
367           "config.worktree" is per-working directory (i.e., it’s in
368           GIT_COMMON_DIR/worktrees/<id>/config.worktree)
369

SEE ALSO

371       git-init(1), git-clone(1), git-fetch(1), git-pack-refs(1), git-gc(1),
372       git-checkout(1), gitglossary(7), The Git User’s Manual[1]
373

GIT

375       Part of the git(1) suite
376

NOTES

378        1. The Git User’s Manual
379           file:///usr/share/doc/git/user-manual.html
380
381
382
383Git 2.39.1                        2023-01-13            GITREPOSITORY-LAYOU(5)
Impressum