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