@matheusbsbs / matheus-bagliano / commits / 556b6600b2
Fork 0

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.