Merge branch 'lt/tree-2'
[git/git.git] / Documentation / repository-layout.txt
1 git repository layout
2 =====================
3
4 You may find these things in your git repository (`.git`
5 directory for a repository associated with your working tree, or
6 `'project'.git` directory for a public 'bare' repository).
7
8 objects::
9 Object store associated with this repository. Usually
10 an object store is self sufficient (i.e. all the objects
11 that are referred to by an object found in it are also
12 found in it), but there are couple of ways to violate
13 it.
14 +
15 . You could populate the repository by running a commit walker
16 without `-a` option. Depending on which options are given, you
17 could have only commit objects without associated blobs and
18 trees this way, for example. A repository with this kind of
19 incomplete object store is not suitable to be published to the
20 outside world but sometimes useful for private repository.
21 . You can be using `objects/info/alternates` mechanism, or
22 `$GIT_ALTERNATE_OBJECT_DIRECTORIES` mechanism to 'borrow'
23 objects from other object stores. A repository with this kind
24 of incomplete object store is not suitable to be published for
25 use with dumb transports but otherwise is OK as long as
26 `objects/info/alternates` points at the right object stores
27 it borrows from.
28
29 objects/[0-9a-f][0-9a-f]::
30 Traditionally, each object is stored in its own file.
31 They are split into 256 subdirectories using the first
32 two letters from its object name to keep the number of
33 directory entries `objects` directory itself needs to
34 hold. Objects found here are often called 'unpacked'
35 objects.
36
37 objects/pack::
38 Packs (files that store many object in compressed form,
39 along with index files to allow them to be randomly
40 accessed) are found in this directory.
41
42 objects/info::
43 Additional information about the object store is
44 recorded in this directory.
45
46 objects/info/packs::
47 This file is to help dumb transports discover what packs
48 are available in this object store. Whenever a pack is
49 added or removed, `git update-server-info` should be run
50 to keep this file up-to-date if the repository is
51 published for dumb transports. `git repack` does this
52 by default.
53
54 objects/info/alternates::
55 This file records absolute filesystem paths of alternate
56 object stores that this object store borrows objects
57 from, one pathname per line.
58
59 refs::
60 References are stored in subdirectories of this
61 directory. The `git prune` command knows to keep
62 objects reachable from refs found in this directory and
63 its subdirectories.
64
65 refs/heads/`name`::
66 records tip-of-the-tree commit objects of branch `name`
67
68 refs/tags/`name`::
69 records any object name (not necessarily a commit
70 object, or a tag object that points at a commit object).
71
72 HEAD::
73 A symlink of the form `refs/heads/'name'` to point at
74 the current branch, if exists. It does not mean much if
75 the repository is not associated with any working tree
76 (i.e. a 'bare' repository), but a valid git repository
77 *must* have such a symlink here. It is legal if the
78 named branch 'name' does not (yet) exist.
79
80 branches::
81 A slightly deprecated way to store shorthands to be used
82 to specify URL to `git fetch`, `git pull` and `git push`
83 commands is to store a file in `branches/'name'` and
84 give 'name' to these commands in place of 'repository'
85 argument.
86
87 hooks::
88 Hooks are customization scripts used by various git
89 commands. A handful of sample hooks are installed when
90 `git init-db` is run, but all of them are disabled by
91 default. To enable, they need to be made executable.
92 Read link:hooks.html[hooks] for more details about
93 each hook.
94
95 index::
96 The current index file for the repository. It is
97 usually not found in a bare repository.
98
99 info::
100 Additional information about the repository is recorded
101 in this directory.
102
103 info/refs::
104 This file is to help dumb transports to discover what
105 refs are available in this repository. Whenever you
106 create/delete a new branch or a new tag, `git
107 update-server-info` should be run to keep this file
108 up-to-date if the repository is published for dumb
109 transports. The `git-receive-pack` command, which is
110 run on a remote repository when you `git push` into it,
111 runs `hooks/update` hook to help you achieve this.
112
113 info/grafts::
114 This file records fake commit ancestry information, to
115 pretend the set of parents a commit has is different
116 from how the commit was actually created. One record
117 per line describes a commit and its fake parents by
118 listing their 40-byte hexadecimal object names separated
119 by a space and terminated by a newline.
120
121 info/exclude::
122 This file, by convention among Porcelains, stores the
123 exclude pattern list. `git status` looks at it, but
124 otherwise it is not looked at by any of the core git
125 commands.
126
127 remotes::
128 Stores shorthands to be used to give URL and default
129 refnames to interact with remote repository to `git
130 fetch`, `git pull` and `git push` commands.
131
132 logs::
133 Records of changes made to refs are stored in this
134 directory. See the documentation on git-update-ref
135 for more information.
136
137 logs/refs/heads/`name`::
138 Records all changes made to the branch tip named `name`.
139
140 logs/refs/tags/`name`::
141 Records all changes made to the tag named `name`.