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