David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 1 | //////////////////////////////////////////////////////////////// |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 2 | |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 3 | GIT - the stupid content tracker |
| 4 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 5 | //////////////////////////////////////////////////////////////// |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 6 | "git" can mean anything, depending on your mood. |
| 7 | |
| 8 | - random three-letter combination that is pronounceable, and not |
| 9 | actually used by any common UNIX command. The fact that it is a |
Pavel Roskin | 90c4851 | 2005-04-14 23:35:00 -0400 | [diff] [blame] | 10 | mispronunciation of "get" may or may not be relevant. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 11 | - stupid. contemptible and despicable. simple. Take your pick from the |
| 12 | dictionary of slang. |
| 13 | - "global information tracker": you're in a good mood, and it actually |
| 14 | works for you. Angels sing, and a light suddenly fills the room. |
| 15 | - "goddamn idiotic truckload of sh*t": when it breaks |
| 16 | |
| 17 | This is a stupid (but extremely fast) directory content manager. It |
| 18 | doesn't do a whole lot, but what it _does_ do is track directory |
| 19 | contents efficiently. |
| 20 | |
| 21 | There are two object abstractions: the "object database", and the |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 22 | "current directory cache" aka "index". |
| 23 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 24 | The Object Database |
| 25 | ~~~~~~~~~~~~~~~~~~~ |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 26 | The object database is literally just a content-addressable collection |
| 27 | of objects. All objects are named by their content, which is |
| 28 | approximated by the SHA1 hash of the object itself. Objects may refer |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 29 | to other objects (by referencing their SHA1 hash), and so you can |
| 30 | build up a hierarchy of objects. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 31 | |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 32 | All objects have a statically determined "type" aka "tag", which is |
| 33 | determined at object creation time, and which identifies the format of |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 34 | the object (i.e. how it is used, and how it can refer to other |
| 35 | objects). There are currently four different object types: "blob", |
| 36 | "tree", "commit" and "tag". |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 37 | |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 38 | A "blob" object cannot refer to any other object, and is, like the tag |
| 39 | implies, a pure storage object containing some user data. It is used to |
Pavel Roskin | 90c4851 | 2005-04-14 23:35:00 -0400 | [diff] [blame] | 40 | actually store the file data, i.e. a blob object is associated with some |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 41 | particular version of some file. |
| 42 | |
| 43 | A "tree" object is an object that ties one or more "blob" objects into a |
| 44 | directory structure. In addition, a tree object can refer to other tree |
| 45 | objects, thus creating a directory hierarchy. |
| 46 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 47 | A "commit" object ties such directory hierarchies together into |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 48 | a DAG of revisions - each "commit" is associated with exactly one tree |
| 49 | (the directory hierarchy at the time of the commit). In addition, a |
| 50 | "commit" refers to one or more "parent" commit objects that describe the |
| 51 | history of how we arrived at that directory hierarchy. |
| 52 | |
| 53 | As a special case, a commit object with no parents is called the "root" |
| 54 | object, and is the point of an initial project commit. Each project |
| 55 | must have at least one root, and while you can tie several different |
| 56 | root objects together into one project by creating a commit object which |
| 57 | has two or more separate roots as its ultimate parents, that's probably |
| 58 | just going to confuse people. So aim for the notion of "one root object |
| 59 | per project", even if git itself does not enforce that. |
| 60 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 61 | A "tag" object symbolically identifies and can be used to sign other |
| 62 | objects. It contains the identifier and type of another object, a |
| 63 | symbolic name (of course!) and, optionally, a signature. |
| 64 | |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 65 | Regardless of object type, all objects are share the following |
| 66 | characteristics: they are all in deflated with zlib, and have a header |
| 67 | that not only specifies their tag, but also size information about the |
| 68 | data in the object. It's worth noting that the SHA1 hash that is used |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 69 | to name the object is the hash of the original data (historical note: |
| 70 | in the dawn of the age of git this was the sha1 of the _compressed_ |
| 71 | object) |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 72 | |
| 73 | As a result, the general consistency of an object can always be tested |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 74 | independently of the contents or the type of the object: all objects can |
| 75 | be validated by verifying that (a) their hashes match the content of the |
| 76 | file and (b) the object successfully inflates to a stream of bytes that |
| 77 | forms a sequence of <ascii tag without space> + <space> + <ascii decimal |
| 78 | size> + <byte\0> + <binary object data>. |
| 79 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 80 | The structured objects can further have their structure and |
| 81 | connectivity to other objects verified. This is generally done with |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 82 | the "git-fsck-cache" program, which generates a full dependency graph |
| 83 | of all objects, and verifies their internal consistency (in addition |
| 84 | to just verifying their superficial consistency through the hash). |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 85 | |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 86 | The object types in some more detail: |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 87 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 88 | Blob Object |
| 89 | ~~~~~~~~~~~ |
| 90 | A "blob" object is nothing but a binary blob of data, and doesn't |
| 91 | refer to anything else. There is no signature or any other |
| 92 | verification of the data, so while the object is consistent (it _is_ |
| 93 | indexed by its sha1 hash, so the data itself is certainly correct), it |
| 94 | has absolutely no other attributes. No name associations, no |
| 95 | permissions. It is purely a blob of data (i.e. normally "file |
| 96 | contents"). |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 97 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 98 | In particular, since the blob is entirely defined by its data, if two |
| 99 | files in a directory tree (or in multiple different versions of the |
| 100 | repository) have the same contents, they will share the same blob |
| 101 | object. The object is totally independent of it's location in the |
| 102 | directory tree, and renaming a file does not change the object that |
| 103 | file is associated with in any way. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 104 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 105 | A blob is created with link:git-write-blob.html[git-write-blob] and |
| 106 | it's data can be accessed by link:git-cat-file.html[git-cat-file] |
| 107 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 108 | Tree Object |
| 109 | ~~~~~~~~~~~ |
| 110 | The next hierarchical object type is the "tree" object. A tree object |
| 111 | is a list of mode/name/blob data, sorted by name. Alternatively, the |
| 112 | mode data may specify a directory mode, in which case instead of |
| 113 | naming a blob, that name is associated with another TREE object. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 114 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 115 | Like the "blob" object, a tree object is uniquely determined by the |
| 116 | set contents, and so two separate but identical trees will always |
| 117 | share the exact same object. This is true at all levels, i.e. it's |
| 118 | true for a "leaf" tree (which does not refer to any other trees, only |
| 119 | blobs) as well as for a whole subdirectory. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 120 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 121 | For that reason a "tree" object is just a pure data abstraction: it |
| 122 | has no history, no signatures, no verification of validity, except |
| 123 | that since the contents are again protected by the hash itself, we can |
| 124 | trust that the tree is immutable and its contents never change. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 125 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 126 | So you can trust the contents of a tree to be valid, the same way you |
| 127 | can trust the contents of a blob, but you don't know where those |
| 128 | contents _came_ from. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 129 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 130 | Side note on trees: since a "tree" object is a sorted list of |
| 131 | "filename+content", you can create a diff between two trees without |
| 132 | actually having to unpack two trees. Just ignore all common parts, |
| 133 | and your diff will look right. In other words, you can effectively |
| 134 | (and efficiently) tell the difference between any two random trees by |
| 135 | O(n) where "n" is the size of the difference, rather than the size of |
| 136 | the tree. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 137 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 138 | Side note 2 on trees: since the name of a "blob" depends entirely and |
| 139 | exclusively on its contents (i.e. there are no names or permissions |
| 140 | involved), you can see trivial renames or permission changes by |
| 141 | noticing that the blob stayed the same. However, renames with data |
| 142 | changes need a smarter "diff" implementation. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 143 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 144 | A tree is created with link:git-write-tree.html[git-write-tree] and |
| 145 | it's data can be accessed by link:git-ls-tree.html[git-ls-tree] |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 146 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 147 | Commit Object |
| 148 | ~~~~~~~~~~~~~ |
| 149 | The "commit" object is an object that introduces the notion of |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 150 | history into the picture. In contrast to the other objects, it |
| 151 | doesn't just describe the physical state of a tree, it describes how |
| 152 | we got there, and why. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 153 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 154 | A "commit" is defined by the tree-object that it results in, the |
| 155 | parent commits (zero, one or more) that led up to that point, and a |
| 156 | comment on what happened. Again, a commit is not trusted per se: |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 157 | the contents are well-defined and "safe" due to the cryptographically |
| 158 | strong signatures at all levels, but there is no reason to believe |
| 159 | that the tree is "good" or that the merge information makes sense. |
| 160 | The parents do not have to actually have any relationship with the |
| 161 | result, for example. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 162 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 163 | Note on commits: unlike real SCM's, commits do not contain |
| 164 | rename information or file mode chane information. All of that is |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 165 | implicit in the trees involved (the result tree, and the result trees |
| 166 | of the parents), and describing that makes no sense in this idiotic |
| 167 | file manager. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 168 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 169 | A commit is created with link:git-commit-tree.html[git-commit-tree] and |
| 170 | it's data can be accessed by link:git-cat-file.html[git-cat-file] |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 171 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 172 | Trust |
| 173 | ~~~~~ |
| 174 | An aside on the notion of "trust". Trust is really outside the scope |
| 175 | of "git", but it's worth noting a few things. First off, since |
| 176 | everything is hashed with SHA1, you _can_ trust that an object is |
| 177 | intact and has not been messed with by external sources. So the name |
| 178 | of an object uniquely identifies a known state - just not a state that |
| 179 | you may want to trust. |
| 180 | |
| 181 | Furthermore, since the SHA1 signature of a commit refers to the |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 182 | SHA1 signatures of the tree it is associated with and the signatures |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 183 | of the parent, a single named commit specifies uniquely a whole set |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 184 | of history, with full contents. You can't later fake any step of the |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 185 | way once you have the name of a commit. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 186 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 187 | So to introduce some real trust in the system, the only thing you need |
| 188 | to do is to digitally sign just _one_ special note, which includes the |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 189 | name of a top-level commit. Your digital signature shows others |
| 190 | that you trust that commit, and the immutability of the history of |
| 191 | commits tells others that they can trust the whole history. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 192 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 193 | In other words, you can easily validate a whole archive by just |
| 194 | sending out a single email that tells the people the name (SHA1 hash) |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 195 | of the top commit, and digitally sign that email using something |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 196 | like GPG/PGP. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 197 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 198 | To assist in this, git also provides the tag object... |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 199 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 200 | Tag Object |
| 201 | ~~~~~~~~~~ |
| 202 | Git provides the "tag" object to simplify creating, managing and |
| 203 | exchanging symbolic and signed tokens. The "tag" object at its |
| 204 | simplest simply symbolically identifies another object by containing |
| 205 | the sha1, type and symbolic name. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 206 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 207 | However it can optionally contain additional signature information |
| 208 | (which git doesn't care about as long as there's less than 8k of |
| 209 | it). This can then be verified externally to git. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 210 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 211 | Note that despite the tag features, "git" itself only handles content |
| 212 | integrity; the trust framework (and signature provision and |
| 213 | verification) has to come from outside. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 214 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 215 | A tag is created with link:git-mktag.html[git-mktag] and |
| 216 | it's data can be accessed by link:git-cat-file.html[git-cat-file] |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 217 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 218 | The "index" aka "Current Directory Cache" |
| 219 | ----------------------------------------- |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 220 | The index is a simple binary file, which contains an efficient |
| 221 | representation of a virtual directory content at some random time. It |
| 222 | does so by a simple array that associates a set of names, dates, |
| 223 | permissions and content (aka "blob") objects together. The cache is |
| 224 | always kept ordered by name, and names are unique (with a few very |
| 225 | specific rules) at any point in time, but the cache has no long-term |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 226 | meaning, and can be partially updated at any time. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 227 | |
| 228 | In particular, the index certainly does not need to be consistent with |
| 229 | the current directory contents (in fact, most operations will depend on |
| 230 | different ways to make the index _not_ be consistent with the directory |
| 231 | hierarchy), but it has three very important attributes: |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 232 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 233 | '(a) it can re-generate the full state it caches (not just the |
| 234 | directory structure: it contains pointers to the "blob" objects so |
| 235 | that it can regenerate the data too)' |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 236 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 237 | As a special case, there is a clear and unambiguous one-way mapping |
| 238 | from a current directory cache to a "tree object", which can be |
| 239 | efficiently created from just the current directory cache without |
| 240 | actually looking at any other data. So a directory cache at any one |
| 241 | time uniquely specifies one and only one "tree" object (but has |
| 242 | additional data to make it easy to match up that tree object with what |
| 243 | has happened in the directory) |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 244 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 245 | '(b) it has efficient methods for finding inconsistencies between that |
| 246 | cached state ("tree object waiting to be instantiated") and the |
| 247 | current state.' |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 248 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 249 | '(c) it can additionally efficiently represent information about merge |
| 250 | conflicts between different tree objects, allowing each pathname to be |
| 251 | associated with sufficient information about the trees involved that |
| 252 | you can create a three-way merge between them.' |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 253 | |
| 254 | Those are the three ONLY things that the directory cache does. It's a |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 255 | cache, and the normal operation is to re-generate it completely from a |
| 256 | known tree object, or update/compare it with a live tree that is being |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 257 | developed. If you blow the directory cache away entirely, you generally |
| 258 | haven't lost any information as long as you have the name of the tree |
| 259 | that it described. |
Linus Torvalds | e83c516 | 2005-04-07 15:13:13 -0700 | [diff] [blame] | 260 | |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 261 | At the same time, the directory index is at the same time also the |
| 262 | staging area for creating new trees, and creating a new tree always |
| 263 | involves a controlled modification of the index file. In particular, |
| 264 | the index file can have the representation of an intermediate tree that |
| 265 | has not yet been instantiated. So the index can be thought of as a |
| 266 | write-back cache, which can contain dirty information that has not yet |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 267 | been written back to the backing store. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 268 | |
| 269 | |
| 270 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 271 | The Workflow |
| 272 | ------------ |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 273 | Generally, all "git" operations work on the index file. Some operations |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 274 | work *purely* on the index file (showing the current state of the |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 275 | index), but most operations move data to and from the index file. Either |
| 276 | from the database or from the working directory. Thus there are four |
| 277 | main combinations: |
| 278 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 279 | 1) working directory -> index |
| 280 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 281 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 282 | You update the index with information from the working directory with |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 283 | the link:git-update-cache.html[git-update-cache] command. You |
| 284 | generally update the index information by just specifying the filename |
| 285 | you want to update, like so: |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 286 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 287 | git-update-cache filename |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 288 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 289 | but to avoid common mistakes with filename globbing etc, the command |
| 290 | will not normally add totally new entries or remove old entries, |
| 291 | i.e. it will normally just update existing cache entries. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 292 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 293 | To tell git that yes, you really do realize that certain files no |
| 294 | longer exist in the archive, or that new files should be added, you |
| 295 | should use the "--remove" and "--add" flags respectively. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 296 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 297 | NOTE! A "--remove" flag does _not_ mean that subsequent filenames will |
| 298 | necessarily be removed: if the files still exist in your directory |
| 299 | structure, the index will be updated with their new status, not |
| 300 | removed. The only thing "--remove" means is that update-cache will be |
| 301 | considering a removed file to be a valid thing, and if the file really |
| 302 | does not exist any more, it will update the index accordingly. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 303 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 304 | As a special case, you can also do "git-update-cache --refresh", which |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 305 | will refresh the "stat" information of each index to match the current |
| 306 | stat information. It will _not_ update the object status itself, and |
| 307 | it will only update the fields that are used to quickly test whether |
| 308 | an object still matches its old backing store object. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 309 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 310 | 2) index -> object database |
| 311 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 312 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 313 | You write your current index file to a "tree" object with the program |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 314 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 315 | git-write-tree |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 316 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 317 | that doesn't come with any options - it will just write out the |
| 318 | current index into the set of tree objects that describe that state, |
| 319 | and it will return the name of the resulting top-level tree. You can |
| 320 | use that tree to re-generate the index at any time by going in the |
| 321 | other direction: |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 322 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 323 | 3) object database -> index |
| 324 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 325 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 326 | You read a "tree" file from the object database, and use that to |
| 327 | populate (and overwrite - don't do this if your index contains any |
| 328 | unsaved state that you might want to restore later!) your current |
| 329 | index. Normal operation is just |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 330 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 331 | git-read-tree <sha1 of tree> |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 332 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 333 | and your index file will now be equivalent to the tree that you saved |
| 334 | earlier. However, that is only your _index_ file: your working |
| 335 | directory contents have not been modified. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 336 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 337 | 4) index -> working directory |
| 338 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 339 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 340 | You update your working directory from the index by "checking out" |
| 341 | files. This is not a very common operation, since normally you'd just |
| 342 | keep your files updated, and rather than write to your working |
| 343 | directory, you'd tell the index files about the changes in your |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 344 | working directory (i.e. "git-update-cache"). |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 345 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 346 | However, if you decide to jump to a new version, or check out somebody |
| 347 | else's version, or just restore a previous tree, you'd populate your |
| 348 | index file with read-tree, and then you need to check out the result |
| 349 | with |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 350 | git-checkout-cache filename |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 351 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 352 | or, if you want to check out all of the index, use "-a". |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 353 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 354 | NOTE! git-checkout-cache normally refuses to overwrite old files, so |
| 355 | if you have an old version of the tree already checked out, you will |
| 356 | need to use the "-f" flag (_before_ the "-a" flag or the filename) to |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 357 | _force_ the checkout. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 358 | |
| 359 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 360 | Finally, there are a few odds and ends which are not purely moving |
| 361 | from one representation to the other: |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 362 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 363 | 5) Tying it all together |
| 364 | ~~~~~~~~~~~~~~~~~~~~~~~~ |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 365 | To commit a tree you have instantiated with "git-write-tree", you'd |
| 366 | create a "commit" object that refers to that tree and the history |
| 367 | behind it - most notably the "parent" commits that preceded it in |
| 368 | history. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 369 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 370 | Normally a "commit" has one parent: the previous state of the tree |
| 371 | before a certain change was made. However, sometimes it can have two |
| 372 | or more parent commits, in which case we call it a "merge", due to the |
| 373 | fact that such a commit brings together ("merges") two or more |
| 374 | previous states represented by other commits. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 375 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 376 | In other words, while a "tree" represents a particular directory state |
| 377 | of a working directory, a "commit" represents that state in "time", |
| 378 | and explains how we got there. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 379 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 380 | You create a commit object by giving it the tree that describes the |
| 381 | state at the time of the commit, and a list of parents: |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 382 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 383 | git-commit-tree <tree> -p <parent> [-p <parent2> ..] |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 384 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 385 | and then giving the reason for the commit on stdin (either through |
| 386 | redirection from a pipe or file, or by just typing it at the tty). |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 387 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 388 | git-commit-tree will return the name of the object that represents |
| 389 | that commit, and you should save it away for later use. Normally, |
| 390 | you'd commit a new "HEAD" state, and while git doesn't care where you |
| 391 | save the note about that state, in practice we tend to just write the |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 392 | result to the file ".git/HEAD", so that we can always see what the |
| 393 | last committed state was. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 394 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 395 | 6) Examining the data |
| 396 | ~~~~~~~~~~~~~~~~~~~~~ |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 397 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 398 | You can examine the data represented in the object database and the |
| 399 | index with various helper tools. For every object, you can use |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 400 | link:git-cat-file.html[git-cat-file] to examine details about the |
| 401 | object: |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 402 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 403 | git-cat-file -t <objectname> |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 404 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 405 | shows the type of the object, and once you have the type (which is |
| 406 | usually implicit in where you find the object), you can use |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 407 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 408 | git-cat-file blob|tree|commit <objectname> |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 409 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 410 | to show its contents. NOTE! Trees have binary content, and as a result |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 411 | there is a special helper for showing that content, called |
| 412 | "git-ls-tree", which turns the binary content into a more easily |
| 413 | readable form. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 414 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 415 | It's especially instructive to look at "commit" objects, since those |
| 416 | tend to be small and fairly self-explanatory. In particular, if you |
| 417 | follow the convention of having the top commit name in ".git/HEAD", |
| 418 | you can do |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 419 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 420 | git-cat-file commit $(cat .git/HEAD) |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 421 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 422 | to see what the top commit was. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 423 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 424 | 7) Merging multiple trees |
| 425 | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 426 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 427 | Git helps you do a three-way merge, which you can expand to n-way by |
| 428 | repeating the merge procedure arbitrary times until you finally |
| 429 | "commit" the state. The normal situation is that you'd only do one |
| 430 | three-way merge (two parents), and commit it, but if you like to, you |
| 431 | can do multiple parents in one go. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 432 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 433 | To do a three-way merge, you need the two sets of "commit" objects |
| 434 | that you want to merge, use those to find the closest common parent (a |
| 435 | third "commit" object), and then use those commit objects to find the |
| 436 | state of the directory ("tree" object) at these points. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 437 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 438 | To get the "base" for the merge, you first look up the common parent |
| 439 | of two commits with |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 440 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 441 | git-merge-base <commit1> <commit2> |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 442 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 443 | which will return you the commit they are both based on. You should |
| 444 | now look up the "tree" objects of those commits, which you can easily |
| 445 | do with (for example) |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 446 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 447 | git-cat-file commit <commitname> | head -1 |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 448 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 449 | since the tree object information is always the first line in a commit |
| 450 | object. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 451 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 452 | Once you know the three trees you are going to merge (the one |
| 453 | "original" tree, aka the common case, and the two "result" trees, aka |
| 454 | the branches you want to merge), you do a "merge" read into the |
| 455 | index. This will throw away your old index contents, so you should |
| 456 | make sure that you've committed those - in fact you would normally |
| 457 | always do a merge against your last commit (which should thus match |
| 458 | what you have in your current index anyway). |
| 459 | |
| 460 | To do the merge, do |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 461 | |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 462 | git-read-tree -m <origtree> <target1tree> <target2tree> |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 463 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 464 | which will do all trivial merge operations for you directly in the |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 465 | index file, and you can just write the result out with |
| 466 | "git-write-tree". |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 467 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 468 | NOTE! Because the merge is done in the index file, and not in your |
| 469 | working directory, your working directory will no longer match your |
David Greaves | 7096a64 | 2005-05-22 18:44:17 +0100 | [diff] [blame^] | 470 | index. You can use "git-checkout-cache -f -a" to make the effect of |
| 471 | the merge be seen in your working directory. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 472 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 473 | NOTE2! Sadly, many merges aren't trivial. If there are files that have |
| 474 | been added.moved or removed, or if both branches have modified the |
| 475 | same file, you will be left with an index tree that contains "merge |
| 476 | entries" in it. Such an index tree can _NOT_ be written out to a tree |
| 477 | object, and you will have to resolve any such merge clashes using |
| 478 | other tools before you can write out the result. |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 479 | |
Linus Torvalds | 6ad6d3d | 2005-04-17 21:52:23 -0700 | [diff] [blame] | 480 | |
David Greaves | 8ac866a | 2005-05-22 18:44:16 +0100 | [diff] [blame] | 481 | [ fixme: talk about resolving merges here ] |