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