1gitrepository-layout(5) 2======================= 3 4NAME 5---- 6gitrepository-layout - Git Repository Layout 7 8SYNOPSIS 9-------- 10$GIT_DIR/* 11 12DESCRIPTION 13----------- 14 15A Git repository comes in two different flavours: 16 17 * a `.git` directory at the root of the working tree; 18 19 * a `<project>.git` directory that is a 'bare' repository 20 (i.e. without its own working tree), that is typically used for 21 exchanging histories with others by pushing into it and fetching 22 from it. 23 24*Note*: Also you can have a plain text file `.git` at the root of 25your working tree, containing `gitdir: <path>` to point at the real 26directory that has the repository. This mechanism is often used for 27a working tree of a submodule checkout, to allow you in the 28containing superproject to `git checkout` a branch that does not 29have the submodule. The `checkout` has to remove the entire 30submodule working tree, without losing the submodule repository. 31 32These things may exist in a Git repository. 33 34objects:: 35 Object store associated with this repository. Usually 36 an object store is self sufficient (i.e. all the objects 37 that are referred to by an object found in it are also 38 found in it), but there are a few ways to violate it. 39+ 40. You could have an incomplete but locally usable repository 41by creating a shallow clone. See linkgit:git-clone[1]. 42. You could be using the `objects/info/alternates` or 43`$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanisms to 'borrow' 44objects from other object stores. A repository with this kind 45of incomplete object store is not suitable to be published for 46use with dumb transports but otherwise is OK as long as 47`objects/info/alternates` points at the object stores it 48borrows from. 49+ 50This directory is ignored if $GIT_COMMON_DIR is set and 51"$GIT_COMMON_DIR/objects" will be used instead. 52 53objects/[0-9a-f][0-9a-f]:: 54 A newly created object is stored in its own file. 55 The objects are splayed over 256 subdirectories using 56 the first two characters of the sha1 object name to 57 keep the number of directory entries in `objects` 58 itself to a manageable number. Objects found 59 here are often called 'unpacked' (or 'loose') objects. 60 61objects/pack:: 62 Packs (files that store many object in compressed form, 63 along with index files to allow them to be randomly 64 accessed) are found in this directory. 65 66objects/info:: 67 Additional information about the object store is 68 recorded in this directory. 69 70objects/info/packs:: 71 This file is to help dumb transports discover what packs 72 are available in this object store. Whenever a pack is 73 added or removed, `git update-server-info` should be run 74 to keep this file up to date if the repository is 75 published for dumb transports. 'git repack' does this 76 by default. 77 78objects/info/alternates:: 79 This file records paths to alternate object stores that 80 this object store borrows objects from, one pathname per 81 line. Note that not only native Git tools use it locally, 82 but the HTTP fetcher also tries to use it remotely; this 83 will usually work if you have relative paths (relative 84 to the object database, not to the repository!) in your 85 alternates file, but it will not work if you use absolute 86 paths unless the absolute path in filesystem and web URL 87 is the same. See also 'objects/info/http-alternates'. 88 89objects/info/http-alternates:: 90 This file records URLs to alternate object stores that 91 this object store borrows objects from, to be used when 92 the repository is fetched over HTTP. 93 94refs:: 95 References are stored in subdirectories of this 96 directory. The 'git prune' command knows to preserve 97 objects reachable from refs found in this directory and 98 its subdirectories. 99 This directory is ignored (except refs/bisect and 100 refs/worktree) if $GIT_COMMON_DIR is set and 101 "$GIT_COMMON_DIR/refs" will be used instead. 102 103refs/heads/`name`:: 104 records tip-of-the-tree commit objects of branch `name` 105 106refs/tags/`name`:: 107 records any object name (not necessarily a commit 108 object, or a tag object that points at a commit object). 109 110refs/remotes/`name`:: 111 records tip-of-the-tree commit objects of branches copied 112 from a remote repository. 113 114refs/replace/`<obj-sha1>`:: 115 records the SHA-1 of the object that replaces `<obj-sha1>`. 116 This is similar to info/grafts and is internally used and 117 maintained by linkgit:git-replace[1]. Such refs can be exchanged 118 between repositories while grafts are not. 119 120packed-refs:: 121 records the same information as refs/heads/, refs/tags/, 122 and friends record in a more efficient way. See 123 linkgit:git-pack-refs[1]. This file is ignored if $GIT_COMMON_DIR 124 is set and "$GIT_COMMON_DIR/packed-refs" will be used instead. 125 126HEAD:: 127 A symref (see glossary) to the `refs/heads/` namespace 128 describing the currently active branch. It does not mean 129 much if the repository is not associated with any working tree 130 (i.e. a 'bare' repository), but a valid Git repository 131 *must* have the HEAD file; some porcelains may use it to 132 guess the designated "default" branch of the repository 133 (usually 'master'). It is legal if the named branch 134 'name' does not (yet) exist. In some legacy setups, it is 135 a symbolic link instead of a symref that points at the current 136 branch. 137+ 138HEAD can also record a specific commit directly, instead of 139being a symref to point at the current branch. Such a state 140is often called 'detached HEAD.' See linkgit:git-checkout[1] 141for details. 142 143config:: 144 Repository specific configuration file. This file is ignored 145 if $GIT_COMMON_DIR is set and "$GIT_COMMON_DIR/config" will be 146 used instead. 147 148config.worktree:: 149 Working directory specific configuration file for the main 150 working directory in multiple working directory setup (see 151 linkgit:git-worktree[1]). 152 153branches:: 154 A slightly deprecated way to store shorthands to be used 155 to specify a URL to 'git fetch', 'git pull' and 'git push'. 156 A file can be stored as `branches/<name>` and then 157 'name' can be given to these commands in place of 158 'repository' argument. See the REMOTES section in 159 linkgit:git-fetch[1] for details. This mechanism is legacy 160 and not likely to be found in modern repositories. This 161 directory is ignored if $GIT_COMMON_DIR is set and 162 "$GIT_COMMON_DIR/branches" will be used instead. 163 164 165hooks:: 166 Hooks are customization scripts used by various Git 167 commands. A handful of sample hooks are installed when 168 'git init' is run, but all of them are disabled by 169 default. To enable, the `.sample` suffix has to be 170 removed from the filename by renaming. 171 Read linkgit:githooks[5] for more details about 172 each hook. This directory is ignored if $GIT_COMMON_DIR is set 173 and "$GIT_COMMON_DIR/hooks" will be used instead. 174 175common:: 176 When multiple working trees are used, most of files in 177 $GIT_DIR are per-worktree with a few known exceptions. All 178 files under 'common' however will be shared between all 179 working trees. 180 181index:: 182 The current index file for the repository. It is 183 usually not found in a bare repository. 184 185sharedindex.<SHA-1>:: 186 The shared index part, to be referenced by $GIT_DIR/index and 187 other temporary index files. Only valid in split index mode. 188 189info:: 190 Additional information about the repository is recorded 191 in this directory. This directory is ignored if $GIT_COMMON_DIR 192 is set and "$GIT_COMMON_DIR/info" will be used instead. 193 194info/refs:: 195 This file helps dumb transports discover what refs are 196 available in this repository. If the repository is 197 published for dumb transports, this file should be 198 regenerated by 'git update-server-info' every time a tag 199 or branch is created or modified. This is normally done 200 from the `hooks/update` hook, which is run by the 201 'git-receive-pack' command when you 'git push' into the 202 repository. 203 204info/grafts:: 205 This file records fake commit ancestry information, to 206 pretend the set of parents a commit has is different 207 from how the commit was actually created. One record 208 per line describes a commit and its fake parents by 209 listing their 40-byte hexadecimal object names separated 210 by a space and terminated by a newline. 211+ 212Note that the grafts mechanism is outdated and can lead to problems 213transferring objects between repositories; see linkgit:git-replace[1] 214for a more flexible and robust system to do the same thing. 215 216info/exclude:: 217 This file, by convention among Porcelains, stores the 218 exclude pattern list. `.gitignore` is the per-directory 219 ignore file. 'git status', 'git add', 'git rm' and 220 'git clean' look at it but the core Git commands do not look 221 at it. See also: linkgit:gitignore[5]. 222 223info/attributes:: 224 Defines which attributes to assign to a path, similar to per-directory 225 `.gitattributes` files. See also: linkgit:gitattributes[5]. 226 227info/sparse-checkout:: 228 This file stores sparse checkout patterns. 229 See also: linkgit:git-read-tree[1]. 230 231remotes:: 232 Stores shorthands for URL and default refnames for use 233 when interacting with remote repositories via 'git fetch', 234 'git pull' and 'git push' commands. See the REMOTES section 235 in linkgit:git-fetch[1] for details. This mechanism is legacy 236 and not likely to be found in modern repositories. This 237 directory is ignored if $GIT_COMMON_DIR is set and 238 "$GIT_COMMON_DIR/remotes" will be used instead. 239 240logs:: 241 Records of changes made to refs are stored in this directory. 242 See linkgit:git-update-ref[1] for more information. This 243 directory is ignored if $GIT_COMMON_DIR is set and 244 "$GIT_COMMON_DIR/logs" will be used instead. 245 246logs/refs/heads/`name`:: 247 Records all changes made to the branch tip named `name`. 248 249logs/refs/tags/`name`:: 250 Records all changes made to the tag named `name`. 251 252shallow:: 253 This is similar to `info/grafts` but is internally used 254 and maintained by shallow clone mechanism. See `--depth` 255 option to linkgit:git-clone[1] and linkgit:git-fetch[1]. This 256 file is ignored if $GIT_COMMON_DIR is set and 257 "$GIT_COMMON_DIR/shallow" will be used instead. 258 259commondir:: 260 If this file exists, $GIT_COMMON_DIR (see linkgit:git[1]) will 261 be set to the path specified in this file if it is not 262 explicitly set. If the specified path is relative, it is 263 relative to $GIT_DIR. The repository with commondir is 264 incomplete without the repository pointed by "commondir". 265 266modules:: 267 Contains the git-repositories of the submodules. 268 269worktrees:: 270 Contains administrative data for linked 271 working trees. Each subdirectory contains the working tree-related 272 part of a linked working tree. This directory is ignored if 273 $GIT_COMMON_DIR is set, in which case 274 "$GIT_COMMON_DIR/worktrees" will be used instead. 275 276worktrees/<id>/gitdir:: 277 A text file containing the absolute path back to the .git file 278 that points to here. This is used to check if the linked 279 repository has been manually removed and there is no need to 280 keep this directory any more. The mtime of this file should be 281 updated every time the linked repository is accessed. 282 283worktrees/<id>/locked:: 284 If this file exists, the linked working tree may be on a 285 portable device and not available. The presence of this file 286 prevents `worktrees/<id>` from being pruned either automatically 287 or manually by `git worktree prune`. The file may contain a string 288 explaining why the repository is locked. 289 290worktrees/<id>/config.worktree:: 291 Working directory specific configuration file. 292 293include::technical/repository-version.txt[] 294 295SEE ALSO 296-------- 297linkgit:git-init[1], 298linkgit:git-clone[1], 299linkgit:git-fetch[1], 300linkgit:git-pack-refs[1], 301linkgit:git-gc[1], 302linkgit:git-checkout[1], 303linkgit:gitglossary[7], 304link:user-manual.html[The Git User's Manual] 305 306GIT 307--- 308Part of the linkgit:git[1] suite