1GITREPOSITORY-LAYOUT(5) Git Manual GITREPOSITORY-LAYOUT(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 objects 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, refs/rewritten and refs/worktree) if
93 $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/refs" will be used
94 instead.
95 refs/heads/name
97 records tip-of-the-tree commit objects of branch name
98 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 refs/remotes/name
104 records tip-of-the-tree commit objects of branches copied from a
105 remote repository.
106 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 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 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 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 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 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 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 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 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 index
168 The current index file for the repository. It is usually not found
169 in a bare repository.
170 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 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 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 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 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 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 info/attributes
207 Defines which attributes to assign to a path, similar to
208 per-directory .gitattributes files. See also: gitattributes(5).
209 info/sparse-checkout
211 This file stores sparse checkout patterns. See also: git-read-
212 tree(1).
213 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 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 logs/refs/heads/name
229 Records all changes made to the branch tip named name.
230 logs/refs/tags/name
232 Records all changes made to the tag named name.
233 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 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 modules
248 Contains the git-repositories of the submodules.
249 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 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 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 worktrees/<id>/config.worktree
271 Working directory specific configuration file.
272
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 Because of this rule, version bumps should be kept to an absolute
283 minimum. Instead, we generally prefer these strategies:
284 • bumping format version numbers of individual data files (e.g.,
286 index, packfiles, etc). This restricts the incompatibilities only
287 to those files.
288 • 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 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 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 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 The currently defined format versions are:
313 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 Version 1
321 This format is identical to version 0, with the following exceptions:
322 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 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 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 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 The defined extensions are:
343 noop
345 This extension does not change git’s behavior at all. It is useful
346 only for testing format-1 compatibility.
347 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 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 The value of this key is the name of the promisor remote.
362 worktreeConfig
364 If set, by default "git config" reads from both "config" and
365 "config.worktree" files 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
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
375 Part of the git(1) suite
376
378 1. The Git User’s Manual
379 file:///usr/share/doc/git/user-manual.html
380Git 2.43.0 11/20/2023 GITREPOSITORY-LAYOUT(5)