git-format-patch: do not crash with format.headers without value.
[git/git.git] / README
CommitLineData
8ac866a8 1////////////////////////////////////////////////////////////////
6ad6d3d3 2
e83c5163
LT
3 GIT - the stupid content tracker
4
8ac866a8 5////////////////////////////////////////////////////////////////
e83c5163
LT
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
90c4851b 10 mispronunciation of "get" may or may not be relevant.
e83c5163
LT
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
17This is a stupid (but extremely fast) directory content manager. It
8db9307c 18doesn't do a whole lot, but what it 'does' do is track directory
e83c5163
LT
19contents efficiently.
20
21There are two object abstractions: the "object database", and the
6ad6d3d3
LT
22"current directory cache" aka "index".
23
8ac866a8
DG
24The Object Database
25~~~~~~~~~~~~~~~~~~~
e83c5163
LT
26The object database is literally just a content-addressable collection
27of objects. All objects are named by their content, which is
28approximated by the SHA1 hash of the object itself. Objects may refer
8ac866a8
DG
29to other objects (by referencing their SHA1 hash), and so you can
30build up a hierarchy of objects.
e83c5163 31
6ad6d3d3
LT
32All objects have a statically determined "type" aka "tag", which is
33determined at object creation time, and which identifies the format of
7096a645 34the object (i.e. how it is used, and how it can refer to other
c4584ae3
JH
35objects). There are currently four different object types: "blob",
36"tree", "commit" and "tag".
6ad6d3d3 37
2fa090b6 38A "blob" object cannot refer to any other object, and is, like the type
6ad6d3d3 39implies, a pure storage object containing some user data. It is used to
90c4851b 40actually store the file data, i.e. a blob object is associated with some
6ad6d3d3
LT
41particular version of some file.
42
43A "tree" object is an object that ties one or more "blob" objects into a
44directory structure. In addition, a tree object can refer to other tree
45objects, thus creating a directory hierarchy.
46
7096a645 47A "commit" object ties such directory hierarchies together into
6ad6d3d3
LT
48a 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
51history of how we arrived at that directory hierarchy.
52
53As a special case, a commit object with no parents is called the "root"
54object, and is the point of an initial project commit. Each project
55must have at least one root, and while you can tie several different
56root objects together into one project by creating a commit object which
57has two or more separate roots as its ultimate parents, that's probably
58just going to confuse people. So aim for the notion of "one root object
59per project", even if git itself does not enforce that.
60
8ac866a8
DG
61A "tag" object symbolically identifies and can be used to sign other
62objects. It contains the identifier and type of another object, a
63symbolic name (of course!) and, optionally, a signature.
64
2aef5bba
DG
65Regardless of object type, all objects share the following
66characteristics: they are all deflated with zlib, and have a header
2fa090b6 67that not only specifies their type, but also provides size information
2aef5bba 68about the data in the object. It's worth noting that the SHA1 hash
8db9307c
JH
69that is used to name the object is the hash of the original data
70plus this header, so `sha1sum` 'file' does not match the object name
71for 'file'.
c4584ae3 72(Historical note: in the dawn of the age of git the hash
8db9307c 73was the sha1 of the 'compressed' object.)
6ad6d3d3
LT
74
75As a result, the general consistency of an object can always be tested
e83c5163
LT
76independently of the contents or the type of the object: all objects can
77be validated by verifying that (a) their hashes match the content of the
78file and (b) the object successfully inflates to a stream of bytes that
2fa090b6 79forms a sequence of <ascii type without space> + <space> + <ascii decimal
e83c5163
LT
80size> + <byte\0> + <binary object data>.
81
8ac866a8
DG
82The structured objects can further have their structure and
83connectivity to other objects verified. This is generally done with
215a7ad1 84the `git-fsck-objects` program, which generates a full dependency graph
7096a645
DG
85of all objects, and verifies their internal consistency (in addition
86to just verifying their superficial consistency through the hash).
6ad6d3d3
LT
87
88The object types in some more detail:
89
8ac866a8
DG
90Blob Object
91~~~~~~~~~~~
92A "blob" object is nothing but a binary blob of data, and doesn't
93refer to anything else. There is no signature or any other
8db9307c 94verification of the data, so while the object is consistent (it 'is'
8ac866a8
DG
95indexed by its sha1 hash, so the data itself is certainly correct), it
96has absolutely no other attributes. No name associations, no
97permissions. It is purely a blob of data (i.e. normally "file
98contents").
99
100In particular, since the blob is entirely defined by its data, if two
101files in a directory tree (or in multiple different versions of the
102repository) have the same contents, they will share the same blob
cdacb620 103object. The object is totally independent of its location in the
8ac866a8
DG
104directory tree, and renaming a file does not change the object that
105file is associated with in any way.
106
a7154e91
SV
107A blob is typically created when gitlink:git-update-index[1]
108is run, and its data can be accessed by gitlink:git-cat-file[1].
7096a645 109
8ac866a8
DG
110Tree Object
111~~~~~~~~~~~
112The next hierarchical object type is the "tree" object. A tree object
113is a list of mode/name/blob data, sorted by name. Alternatively, the
114mode data may specify a directory mode, in which case instead of
115naming a blob, that name is associated with another TREE object.
116
117Like the "blob" object, a tree object is uniquely determined by the
118set contents, and so two separate but identical trees will always
119share the exact same object. This is true at all levels, i.e. it's
120true for a "leaf" tree (which does not refer to any other trees, only
121blobs) as well as for a whole subdirectory.
122
123For that reason a "tree" object is just a pure data abstraction: it
124has no history, no signatures, no verification of validity, except
125that since the contents are again protected by the hash itself, we can
126trust that the tree is immutable and its contents never change.
127
128So you can trust the contents of a tree to be valid, the same way you
129can trust the contents of a blob, but you don't know where those
8db9307c 130contents 'came' from.
8ac866a8
DG
131
132Side note on trees: since a "tree" object is a sorted list of
133"filename+content", you can create a diff between two trees without
134actually having to unpack two trees. Just ignore all common parts,
135and your diff will look right. In other words, you can effectively
136(and efficiently) tell the difference between any two random trees by
137O(n) where "n" is the size of the difference, rather than the size of
138the tree.
139
140Side note 2 on trees: since the name of a "blob" depends entirely and
141exclusively on its contents (i.e. there are no names or permissions
142involved), you can see trivial renames or permission changes by
143noticing that the blob stayed the same. However, renames with data
144changes need a smarter "diff" implementation.
145
a7154e91
SV
146A tree is created with gitlink:git-write-tree[1] and
147its data can be accessed by gitlink:git-ls-tree[1].
148Two trees can be compared with gitlink:git-diff-tree[1].
8ac866a8 149
7096a645
DG
150Commit Object
151~~~~~~~~~~~~~
152The "commit" object is an object that introduces the notion of
8ac866a8
DG
153history into the picture. In contrast to the other objects, it
154doesn't just describe the physical state of a tree, it describes how
155we got there, and why.
156
7096a645
DG
157A "commit" is defined by the tree-object that it results in, the
158parent commits (zero, one or more) that led up to that point, and a
159comment on what happened. Again, a commit is not trusted per se:
8ac866a8
DG
160the contents are well-defined and "safe" due to the cryptographically
161strong signatures at all levels, but there is no reason to believe
162that the tree is "good" or that the merge information makes sense.
163The parents do not have to actually have any relationship with the
164result, for example.
165
7096a645 166Note on commits: unlike real SCM's, commits do not contain
8db9307c 167rename information or file mode change information. All of that is
8ac866a8
DG
168implicit in the trees involved (the result tree, and the result trees
169of the parents), and describing that makes no sense in this idiotic
170file manager.
171
a7154e91
SV
172A commit is created with gitlink:git-commit-tree[1] and
173its data can be accessed by gitlink:git-cat-file[1].
7096a645
DG
174
175Trust
176~~~~~
177An aside on the notion of "trust". Trust is really outside the scope
178of "git", but it's worth noting a few things. First off, since
8db9307c 179everything is hashed with SHA1, you 'can' trust that an object is
7096a645
DG
180intact and has not been messed with by external sources. So the name
181of an object uniquely identifies a known state - just not a state that
182you may want to trust.
8ac866a8 183
7096a645 184Furthermore, since the SHA1 signature of a commit refers to the
8ac866a8 185SHA1 signatures of the tree it is associated with and the signatures
7096a645 186of the parent, a single named commit specifies uniquely a whole set
8ac866a8 187of history, with full contents. You can't later fake any step of the
7096a645 188way once you have the name of a commit.
8ac866a8
DG
189
190So to introduce some real trust in the system, the only thing you need
8db9307c 191to do is to digitally sign just 'one' special note, which includes the
7096a645
DG
192name of a top-level commit. Your digital signature shows others
193that you trust that commit, and the immutability of the history of
194commits tells others that they can trust the whole history.
8ac866a8
DG
195
196In other words, you can easily validate a whole archive by just
197sending out a single email that tells the people the name (SHA1 hash)
7096a645 198of the top commit, and digitally sign that email using something
8ac866a8
DG
199like GPG/PGP.
200
7096a645 201To assist in this, git also provides the tag object...
8ac866a8 202
7096a645
DG
203Tag Object
204~~~~~~~~~~
205Git provides the "tag" object to simplify creating, managing and
206exchanging symbolic and signed tokens. The "tag" object at its
207simplest simply symbolically identifies another object by containing
208the sha1, type and symbolic name.
8ac866a8 209
7096a645
DG
210However it can optionally contain additional signature information
211(which git doesn't care about as long as there's less than 8k of
212it). This can then be verified externally to git.
8ac866a8 213
7096a645
DG
214Note that despite the tag features, "git" itself only handles content
215integrity; the trust framework (and signature provision and
216verification) has to come from outside.
8ac866a8 217
a7154e91
SV
218A tag is created with gitlink:git-mktag[1],
219its data can be accessed by gitlink:git-cat-file[1],
8db9307c 220and the signature can be verified by
a7154e91 221gitlink:git-verify-tag[1].
8ac866a8 222
2aef5bba 223
8ac866a8
DG
224The "index" aka "Current Directory Cache"
225-----------------------------------------
6ad6d3d3
LT
226The index is a simple binary file, which contains an efficient
227representation of a virtual directory content at some random time. It
228does so by a simple array that associates a set of names, dates,
229permissions and content (aka "blob") objects together. The cache is
230always kept ordered by name, and names are unique (with a few very
231specific rules) at any point in time, but the cache has no long-term
8ac866a8 232meaning, and can be partially updated at any time.
6ad6d3d3
LT
233
234In particular, the index certainly does not need to be consistent with
235the current directory contents (in fact, most operations will depend on
8db9307c 236different ways to make the index 'not' be consistent with the directory
6ad6d3d3 237hierarchy), but it has three very important attributes:
e83c5163 238
8ac866a8
DG
239'(a) it can re-generate the full state it caches (not just the
240directory structure: it contains pointers to the "blob" objects so
241that it can regenerate the data too)'
e83c5163 242
8ac866a8
DG
243As a special case, there is a clear and unambiguous one-way mapping
244from a current directory cache to a "tree object", which can be
245efficiently created from just the current directory cache without
246actually looking at any other data. So a directory cache at any one
247time uniquely specifies one and only one "tree" object (but has
248additional data to make it easy to match up that tree object with what
249has happened in the directory)
e83c5163 250
8ac866a8
DG
251'(b) it has efficient methods for finding inconsistencies between that
252cached state ("tree object waiting to be instantiated") and the
253current state.'
e83c5163 254
8ac866a8
DG
255'(c) it can additionally efficiently represent information about merge
256conflicts between different tree objects, allowing each pathname to be
257associated with sufficient information about the trees involved that
258you can create a three-way merge between them.'
6ad6d3d3
LT
259
260Those are the three ONLY things that the directory cache does. It's a
e83c5163
LT
261cache, and the normal operation is to re-generate it completely from a
262known tree object, or update/compare it with a live tree that is being
6ad6d3d3
LT
263developed. If you blow the directory cache away entirely, you generally
264haven't lost any information as long as you have the name of the tree
265that it described.
266
8db9307c 267At the same time, the index is at the same time also the
6ad6d3d3
LT
268staging area for creating new trees, and creating a new tree always
269involves a controlled modification of the index file. In particular,
270the index file can have the representation of an intermediate tree that
271has not yet been instantiated. So the index can be thought of as a
272write-back cache, which can contain dirty information that has not yet
8ac866a8 273been written back to the backing store.
6ad6d3d3
LT
274
275
276
8ac866a8
DG
277The Workflow
278------------
6ad6d3d3 279Generally, all "git" operations work on the index file. Some operations
8ac866a8 280work *purely* on the index file (showing the current state of the
6ad6d3d3
LT
281index), but most operations move data to and from the index file. Either
282from the database or from the working directory. Thus there are four
283main combinations:
284
8ac866a8
DG
2851) working directory -> index
286~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6ad6d3d3 287
8ac866a8 288You update the index with information from the working directory with
a7154e91 289the gitlink:git-update-index[1] command. You
7096a645
DG
290generally update the index information by just specifying the filename
291you want to update, like so:
6ad6d3d3 292
215a7ad1 293 git-update-index filename
6ad6d3d3 294
8ac866a8
DG
295but to avoid common mistakes with filename globbing etc, the command
296will not normally add totally new entries or remove old entries,
297i.e. it will normally just update existing cache entries.
6ad6d3d3 298
8ac866a8 299To tell git that yes, you really do realize that certain files no
2fa090b6 300longer exist, or that new files should be added, you
8db9307c 301should use the `--remove` and `--add` flags respectively.
6ad6d3d3 302
8db9307c 303NOTE! A `--remove` flag does 'not' mean that subsequent filenames will
8ac866a8
DG
304necessarily be removed: if the files still exist in your directory
305structure, the index will be updated with their new status, not
8db9307c 306removed. The only thing `--remove` means is that update-cache will be
8ac866a8
DG
307considering a removed file to be a valid thing, and if the file really
308does not exist any more, it will update the index accordingly.
6ad6d3d3 309
215a7ad1 310As a special case, you can also do `git-update-index --refresh`, which
8ac866a8 311will refresh the "stat" information of each index to match the current
8db9307c 312stat information. It will 'not' update the object status itself, and
8ac866a8
DG
313it will only update the fields that are used to quickly test whether
314an object still matches its old backing store object.
6ad6d3d3 315
8ac866a8
DG
3162) index -> object database
317~~~~~~~~~~~~~~~~~~~~~~~~~~~
6ad6d3d3 318
8ac866a8 319You write your current index file to a "tree" object with the program
6ad6d3d3 320
7096a645 321 git-write-tree
6ad6d3d3 322
8ac866a8
DG
323that doesn't come with any options - it will just write out the
324current index into the set of tree objects that describe that state,
325and it will return the name of the resulting top-level tree. You can
326use that tree to re-generate the index at any time by going in the
327other direction:
6ad6d3d3 328
8ac866a8
DG
3293) object database -> index
330~~~~~~~~~~~~~~~~~~~~~~~~~~~
6ad6d3d3 331
8ac866a8
DG
332You read a "tree" file from the object database, and use that to
333populate (and overwrite - don't do this if your index contains any
334unsaved state that you might want to restore later!) your current
335index. Normal operation is just
6ad6d3d3 336
7096a645 337 git-read-tree <sha1 of tree>
6ad6d3d3 338
8ac866a8 339and your index file will now be equivalent to the tree that you saved
8db9307c 340earlier. However, that is only your 'index' file: your working
8ac866a8 341directory contents have not been modified.
6ad6d3d3 342
8ac866a8
DG
3434) index -> working directory
344~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6ad6d3d3 345
8ac866a8
DG
346You update your working directory from the index by "checking out"
347files. This is not a very common operation, since normally you'd just
348keep your files updated, and rather than write to your working
349directory, you'd tell the index files about the changes in your
215a7ad1 350working directory (i.e. `git-update-index`).
6ad6d3d3 351
8ac866a8
DG
352However, if you decide to jump to a new version, or check out somebody
353else's version, or just restore a previous tree, you'd populate your
354index file with read-tree, and then you need to check out the result
355with
8db9307c 356
215a7ad1 357 git-checkout-index filename
6ad6d3d3 358
8db9307c 359or, if you want to check out all of the index, use `-a`.
6ad6d3d3 360
215a7ad1 361NOTE! git-checkout-index normally refuses to overwrite old files, so
7096a645 362if you have an old version of the tree already checked out, you will
8db9307c
JH
363need to use the "-f" flag ('before' the "-a" flag or the filename) to
364'force' the checkout.
6ad6d3d3
LT
365
366
8ac866a8
DG
367Finally, there are a few odds and ends which are not purely moving
368from one representation to the other:
6ad6d3d3 369
8ac866a8
DG
3705) Tying it all together
371~~~~~~~~~~~~~~~~~~~~~~~~
7096a645
DG
372To commit a tree you have instantiated with "git-write-tree", you'd
373create a "commit" object that refers to that tree and the history
374behind it - most notably the "parent" commits that preceded it in
375history.
6ad6d3d3 376
8ac866a8
DG
377Normally a "commit" has one parent: the previous state of the tree
378before a certain change was made. However, sometimes it can have two
379or more parent commits, in which case we call it a "merge", due to the
380fact that such a commit brings together ("merges") two or more
381previous states represented by other commits.
6ad6d3d3 382
8ac866a8
DG
383In other words, while a "tree" represents a particular directory state
384of a working directory, a "commit" represents that state in "time",
385and explains how we got there.
6ad6d3d3 386
8ac866a8
DG
387You create a commit object by giving it the tree that describes the
388state at the time of the commit, and a list of parents:
6ad6d3d3 389
7096a645 390 git-commit-tree <tree> -p <parent> [-p <parent2> ..]
6ad6d3d3 391
8ac866a8
DG
392and then giving the reason for the commit on stdin (either through
393redirection from a pipe or file, or by just typing it at the tty).
6ad6d3d3 394
7096a645
DG
395git-commit-tree will return the name of the object that represents
396that commit, and you should save it away for later use. Normally,
8db9307c 397you'd commit a new `HEAD` state, and while git doesn't care where you
7096a645 398save the note about that state, in practice we tend to just write the
cd0a781c
JH
399result to the file pointed at by `.git/HEAD`, so that we can always see
400what the last committed state was.
6ad6d3d3 401
66158e33
JH
402Here is an ASCII art by Jon Loeliger that illustrates how
403various pieces fit together.
404
405------------
406
407 commit-tree
408 commit obj
409 +----+
410 | |
411 | |
412 V V
413 +-----------+
414 | Object DB |
415 | Backing |
416 | Store |
417 +-----------+
418 ^
419 write-tree | |
420 tree obj | |
421 | | read-tree
422 | | tree obj
423 V
424 +-----------+
425 | Index |
426 | "cache" |
427 +-----------+
428 update-index ^
429 blob obj | |
430 | |
431 checkout-index -u | | checkout-index
432 stat | | blob obj
433 V
434 +-----------+
435 | Working |
436 | Directory |
437 +-----------+
438
439------------
440
441
8ac866a8
DG
4426) Examining the data
443~~~~~~~~~~~~~~~~~~~~~
6ad6d3d3 444
8ac866a8
DG
445You can examine the data represented in the object database and the
446index with various helper tools. For every object, you can use
a7154e91 447gitlink:git-cat-file[1] to examine details about the
7096a645 448object:
6ad6d3d3 449
7096a645 450 git-cat-file -t <objectname>
6ad6d3d3 451
8ac866a8
DG
452shows the type of the object, and once you have the type (which is
453usually implicit in where you find the object), you can use
6ad6d3d3 454
8db9307c 455 git-cat-file blob|tree|commit|tag <objectname>
6ad6d3d3 456
8ac866a8 457to show its contents. NOTE! Trees have binary content, and as a result
7096a645 458there is a special helper for showing that content, called
8db9307c 459`git-ls-tree`, which turns the binary content into a more easily
7096a645 460readable form.
6ad6d3d3 461
8ac866a8
DG
462It's especially instructive to look at "commit" objects, since those
463tend to be small and fairly self-explanatory. In particular, if you
8db9307c 464follow the convention of having the top commit name in `.git/HEAD`,
8ac866a8 465you can do
6ad6d3d3 466
cd0a781c 467 git-cat-file commit HEAD
6ad6d3d3 468
8ac866a8 469to see what the top commit was.
6ad6d3d3 470
8ac866a8
DG
4717) Merging multiple trees
472~~~~~~~~~~~~~~~~~~~~~~~~~
6ad6d3d3 473
8ac866a8
DG
474Git helps you do a three-way merge, which you can expand to n-way by
475repeating the merge procedure arbitrary times until you finally
476"commit" the state. The normal situation is that you'd only do one
477three-way merge (two parents), and commit it, but if you like to, you
478can do multiple parents in one go.
6ad6d3d3 479
8ac866a8
DG
480To do a three-way merge, you need the two sets of "commit" objects
481that you want to merge, use those to find the closest common parent (a
482third "commit" object), and then use those commit objects to find the
483state of the directory ("tree" object) at these points.
6ad6d3d3 484
8ac866a8
DG
485To get the "base" for the merge, you first look up the common parent
486of two commits with
6ad6d3d3 487
7096a645 488 git-merge-base <commit1> <commit2>
6ad6d3d3 489
8ac866a8
DG
490which will return you the commit they are both based on. You should
491now look up the "tree" objects of those commits, which you can easily
492do with (for example)
6ad6d3d3 493
7096a645 494 git-cat-file commit <commitname> | head -1
6ad6d3d3 495
8ac866a8
DG
496since the tree object information is always the first line in a commit
497object.
498
499Once you know the three trees you are going to merge (the one
500"original" tree, aka the common case, and the two "result" trees, aka
501the branches you want to merge), you do a "merge" read into the
8db9307c 502index. This will complain if it has to throw away your old index contents, so you should
8ac866a8
DG
503make sure that you've committed those - in fact you would normally
504always do a merge against your last commit (which should thus match
505what you have in your current index anyway).
6ad6d3d3 506
8ac866a8 507To do the merge, do
6ad6d3d3 508
8db9307c 509 git-read-tree -m -u <origtree> <yourtree> <targettree>
6ad6d3d3 510
8ac866a8 511which will do all trivial merge operations for you directly in the
7096a645 512index file, and you can just write the result out with
8db9307c
JH
513`git-write-tree`.
514
515Historical note. We did not have `-u` facility when this
516section was first written, so we used to warn that
517the merge is done in the index file, not in your
2fa090b6
JH
518working tree, and your working tree will not match your
519index after this step.
520This is no longer true. The above command, thanks to `-u`
521option, updates your working tree with the merge results for
522paths that have been trivially merged.
6ad6d3d3 523
6ad6d3d3 524
8db9307c
JH
5258) Merging multiple trees, continued
526~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
527
528Sadly, many merges aren't trivial. If there are files that have
8ac866a8
DG
529been added.moved or removed, or if both branches have modified the
530same file, you will be left with an index tree that contains "merge
8db9307c 531entries" in it. Such an index tree can 'NOT' be written out to a tree
8ac866a8
DG
532object, and you will have to resolve any such merge clashes using
533other tools before you can write out the result.
6ad6d3d3 534
8db9307c
JH
535You can examine such index state with `git-ls-files --unmerged`
536command. An example:
537
538------------------------------------------------
539$ git-read-tree -m $orig HEAD $target
540$ git-ls-files --unmerged
541100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1 hello.c
542100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2 hello.c
543100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c
544------------------------------------------------
545
546Each line of the `git-ls-files --unmerged` output begins with
547the blob mode bits, blob SHA1, 'stage number', and the
548filename. The 'stage number' is git's way to say which tree it
549came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`
550tree, and stage3 `$target` tree.
551
552Earlier we said that trivial merges are done inside
553`git-read-tree -m`. For example, if the file did not change
554from `$orig` to `HEAD` nor `$target`, or if the file changed
555from `$orig` to `HEAD` and `$orig` to `$target` the same way,
556obviously the final outcome is what is in `HEAD`. What the
557above example shows is that file `hello.c` was changed from
558`$orig` to `HEAD` and `$orig` to `$target` in a different way.
559You could resolve this by running your favorite 3-way merge
560program, e.g. `diff3` or `merge`, on the blob objects from
561these three stages yourself, like this:
562
563------------------------------------------------
564$ git-cat-file blob 263414f... >hello.c~1
565$ git-cat-file blob 06fa6a2... >hello.c~2
566$ git-cat-file blob cc44c73... >hello.c~3
567$ merge hello.c~2 hello.c~1 hello.c~3
568------------------------------------------------
569
570This would leave the merge result in `hello.c~2` file, along
571with conflict markers if there are conflicts. After verifying
572the merge result makes sense, you can tell git what the final
573merge result for this file is by:
574
575 mv -f hello.c~2 hello.c
215a7ad1 576 git-update-index hello.c
8db9307c 577
215a7ad1 578When a path is in unmerged state, running `git-update-index` for
8db9307c
JH
579that path tells git to mark the path resolved.
580
581The above is the description of a git merge at the lowest level,
582to help you understand what conceptually happens under the hood.
583In practice, nobody, not even git itself, uses three `git-cat-file`
215a7ad1 584for this. There is `git-merge-index` program that extracts the
2fa090b6 585stages to temporary files and calls a "merge" script on it:
8db9307c 586
215a7ad1 587 git-merge-index git-merge-one-file hello.c
8db9307c
JH
588
589and that is what higher level `git resolve` is implemented with.