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