user-manual: rewrite object database discussion
Rewrite the introduction. Rewrite each section completely to make them work in the new order, to add some examples, and to move plumbing commands (like git-commit-tree) to the following chapter. Signed-off-by: J. Bruce Fields <bfields@citi.umich.edu>
J. Bruce Fields committed
Jun 10, 2007 at 15:15 UTC
1bbf1c7900337a646b6ca65c8b3505e784012f39
1 file changed
+196
-139
Documentation/user-manual.txt
+196
-139
@@ -2723,46 +2723,44 @@ database>> and the <<def_index,index>>.
2723
The Object Database
2724
-------------------
2725
2726
-The object database is literally just a content-addressable collection
2727
-of objects. All objects are named by their content, which is
2728
-approximated by the SHA1 hash of the object itself. Objects may refer
2729
-to other objects (by referencing their SHA1 hash), and so you can
2730
-build up a hierarchy of objects.
2731
-
2732
-All objects have a statically determined "type" which is
2733
-determined at object creation time, and which identifies the format of
2734
-the object (i.e. how it is used, and how it can refer to other
2735
-objects). There are currently four different object types: "blob",
2736
-"tree", "commit", and "tag".
2726
2738
-A <<def_blob_object,"blob" object>> cannot refer to any other object,
2739
-and is, as the name implies, a pure storage object containing some
2740
-user data. It is used to actually store the file data, i.e. a blob
2741
-object is associated with some particular version of some file.
2742
-
2743
-A <<def_tree_object,"tree" object>> is an object that ties one or more
2744
-"blob" objects into a directory structure. In addition, a tree object
2745
-can refer to other tree objects, thus creating a directory hierarchy.
2746
-
2747
-A <<def_commit_object,"commit" object>> ties such directory hierarchies
2748
-together into a <<def_DAG,directed acyclic graph>> of revisions - each
2749
-"commit" is associated with exactly one tree (the directory hierarchy at
2750
-the time of the commit). In addition, a "commit" refers to one or more
2751
-"parent" commit objects that describe the history of how we arrived at
2752
-that directory hierarchy.
2753
-
2754
-As a special case, a commit object with no parents is called the "root"
2755
-commit, and is the point of an initial project commit. Each project
2756
-must have at least one root, and while you can tie several different
2757
-root objects together into one project by creating a commit object which
2758
-has two or more separate roots as its ultimate parents, that's probably
2759
-just going to confuse people. So aim for the notion of "one root object
2760
-per project", even if git itself does not enforce that.
2761
-
2762
-A <<def_tag_object,"tag" object>> symbolically identifies and can be
2763
-used to sign other objects. It contains the identifier and type of
2764
-another object, a symbolic name (of course!) and, optionally, a
2765
-signature.
2727
+We already saw in <<understanding-commits>> that all commits are stored
2728
+under a 40-digit "object name". In fact, all the information needed to
2729
+represent the history of a project is stored in objects with such names.
2730
+In each case the name is calculated by taking the SHA1 hash of the
2731
+contents of the object. The SHA1 hash is a cryptographic hash function.
2732
+What that means to us is that it is impossible to find two different
2733
+objects with the same name. This has a number of advantages; among
2734
+others:
2735
+
2736
+- Git can quickly determine whether two objects are identical or not,
2737
+ just by comparing names.
2738
+- Since object names are computed the same way in ever repository, the
2739
+ same content stored in two repositories will always be stored under
2740
+ the same name.
2741
+- Git can detect errors when it reads an object, by checking that the
2742
+ object's name is still the SHA1 hash of its contents.
2743
+
2744
+(See <<object-details>> for the details of the object formatting and
2745
+SHA1 calculation.)
2746
+
2747
+There are four different types of objects: "blob", "tree", "commit", and
2748
+"tag".
2749
+
2750
+- A <<def_blob_object,"blob" object>> is used to store file data.
2751
+- A <<def_tree_object,"tree" object>> is an object that ties one or more
2752
+ "blob" objects into a directory structure. In addition, a tree object
2753
+ can refer to other tree objects, thus creating a directory hierarchy.
2754
+- A <<def_commit_object,"commit" object>> ties such directory hierarchies
2755
+ together into a <<def_DAG,directed acyclic graph>> of revisions - each
2756
+ commit contains the object name of exactly one tree designating the
2757
+ directory hierarchy at the time of the commit. In addition, a commit
2758
+ refers to "parent" commit objects that describe the history of how we
2759
+ arrived at that directory hierarchy.
2760
+- A <<def_tag_object,"tag" object>> symbolically identifies and can be
2761
+ used to sign other objects. It contains the object name and type of
2762
+ another object, a symbolic name (of course!) and, optionally, a
2763
+ signature.
2764
2765
The object types in some more detail:
2766
@@ -2770,109 +2768,142 @@ The object types in some more detail:
2768
Commit Object
2769
~~~~~~~~~~~~~
2770
2773
-The "commit" object is an object that introduces the notion of
2774
-history into the picture. In contrast to the other objects, it
2775
-doesn't just describe the physical state of a tree, it describes how
2776
-we got there, and why.
2777
-
2778
-A "commit" is defined by the tree-object that it results in, the
2779
-parent commits (zero, one or more) that led up to that point, and a
2780
-comment on what happened. Again, a commit is not trusted per se:
2781
-the contents are well-defined and "safe" due to the cryptographically
2782
-strong signatures at all levels, but there is no reason to believe
2783
-that the tree is "good" or that the merge information makes sense.
2784
-The parents do not have to actually have any relationship with the
2785
-result, for example.
2786
-
2787
-Note on commits: unlike some SCM's, commits do not contain
2788
-rename information or file mode change information. All of that is
2789
-implicit in the trees involved (the result tree, and the result trees
2790
-of the parents), and describing that makes no sense in this idiotic
2791
-file manager.
2792
-
2793
-A commit is created with gitlink:git-commit-tree[1] and
2794
-its data can be accessed by gitlink:git-cat-file[1].
2771
+The "commit" object links a physical state of a tree with a description
2772
+of how we got there and why. Use the --pretty=raw option to
2773
+gitlink:git-show[1] or gitlink:git-log[1] to examine your favorite
2774
+commit:
2775
+
2776
+------------------------------------------------
2777
+$ git show -s --pretty=raw 2be7fcb476
2778
+commit 2be7fcb4764f2dbcee52635b91fedb1b3dcf7ab4
2779
+tree fb3a8bdd0ceddd019615af4d57a53f43d8cee2bf
2780
+parent 257a84d9d02e90447b149af58b271c19405edb6a
2781
+author Dave Watson <dwatson@mimvista.com> 1187576872 -0400
2782
+committer Junio C Hamano <gitster@pobox.com> 1187591163 -0700
2783
+
2784
+ Fix misspelling of 'suppress' in docs
2785
+
2786
+ Signed-off-by: Junio C Hamano <gitster@pobox.com>
2787
+------------------------------------------------
2788
+
2789
+As you can see, a commit is defined by:
2790
+
2791
+- a tree: The SHA1 name of a tree object (as defined below), representing
2792
+ the contents of a directory at a certain point in time.
2793
+- parent(s): The SHA1 name of some number of commits which represent the
2794
+ immediately prevoius step(s) in the history of the project. The
2795
+ example above has one parent; merge commits may have more than
2796
+ one. A commit with no parents is called a "root" commit, and
2797
+ represents the initial revision of a project. Each project must have
2798
+ at least one root. A project can also have multiple roots, though
2799
+ that isn't common (or necessarily a good idea).
2800
+- an author: The name of the person responsible for this change, together
2801
+ with its date.
2802
+- a committer: The name of the person who actually created the commit,
2803
+ with the date it was done. This may be different from the author, for
2804
+ example, if the author was someone who wrote a patch and emailed it
2805
+ to the person who used it to create the commit.
2806
+- a comment describing this commit.
2807
+
2808
+Note that a commit does not itself contain any information about what
2809
+actually changed; all changes are calculated by comparing the contents
2810
+of the tree referred to by this commit with the trees associated with
2811
+its parents. In particular, git does not attempt to record file renames
2812
+explicitly, though it can identify cases where the existence of the same
2813
+file data at changing paths suggests a rename. (See, for example, the
2814
+-M option to gitlink:git-diff[1]).
2815
+
2816
+A commit is usually created by gitlink:git-commit[1], which creates a
2817
+commit whose parent is normally the current HEAD, and whose tree is
2818
+taken from the content currently stored in the index.
2819
2820
[[tree-object]]
2821
Tree Object
2822
~~~~~~~~~~~
2823
2800
-The next hierarchical object type is the "tree" object. A tree object
2801
-is a list of mode/name/blob data, sorted by name. Alternatively, the
2802
-mode data may specify a directory mode, in which case instead of
2803
-naming a blob, that name is associated with another TREE object.
2804
-
2805
-Like the "blob" object, a tree object is uniquely determined by the
2806
-set contents, and so two separate but identical trees will always
2807
-share the exact same object. This is true at all levels, i.e. it's
2808
-true for a "leaf" tree (which does not refer to any other trees, only
2809
-blobs) as well as for a whole subdirectory.
2810
-
2811
-For that reason a "tree" object is just a pure data abstraction: it
2812
-has no history, no signatures, no verification of validity, except
2813
-that since the contents are again protected by the hash itself, we can
2814
-trust that the tree is immutable and its contents never change.
2815
-
2816
-So you can trust the contents of a tree to be valid, the same way you
2817
-can trust the contents of a blob, but you don't know where those
2818
-contents 'came' from.
2819
-
2820
-Side note on trees: since a "tree" object is a sorted list of
2821
-"filename+content", you can create a diff between two trees without
2822
-actually having to unpack two trees. Just ignore all common parts,
2823
-and your diff will look right. In other words, you can effectively
2824
-(and efficiently) tell the difference between any two random trees by
2825
-O(n) where "n" is the size of the difference, rather than the size of
2826
-the tree.
2827
-
2828
-Side note 2 on trees: since the name of a "blob" depends entirely and
2829
-exclusively on its contents (i.e. there are no names or permissions
2830
-involved), you can see trivial renames or permission changes by
2831
-noticing that the blob stayed the same. However, renames with data
2832
-changes need a smarter "diff" implementation.
2833
-
2834
-A tree is created with gitlink:git-write-tree[1] and
2835
-its data can be accessed by gitlink:git-ls-tree[1].
2836
-Two trees can be compared with gitlink:git-diff-tree[1].
2824
+The ever-versatile gitlink:git-show[1] command can also be used to
2825
+examine tree objects, but gitlink:git-ls-tree[1] will give you more
2826
+details:
2827
+
2828
+------------------------------------------------
2829
+$ git ls-tree fb3a8bdd0ce
2830
+100644 blob 63c918c667fa005ff12ad89437f2fdc80926e21c .gitignore
2831
+100644 blob 5529b198e8d14decbe4ad99db3f7fb632de0439d .mailmap
2832
+100644 blob 6ff87c4664981e4397625791c8ea3bbb5f2279a3 COPYING
2833
+040000 tree 2fb783e477100ce076f6bf57e4a6f026013dc745 Documentation
2834
+100755 blob 3c0032cec592a765692234f1cba47dfdcc3a9200 GIT-VERSION-GEN
2835
+100644 blob 289b046a443c0647624607d471289b2c7dcd470b INSTALL
2836
+100644 blob 4eb463797adc693dc168b926b6932ff53f17d0b1 Makefile
2837
+100644 blob 548142c327a6790ff8821d67c2ee1eff7a656b52 README
2838
+...
2839
+------------------------------------------------
2840
+
2841
+As you can see, a tree object contains a list of entries, each with a
2842
+mode, object type, SHA1 name, and name, sorted by name. It represents
2843
+the contents of a single directory tree.
2844
+
2845
+The object type may be a blob, representing the contents of a file, or
2846
+another tree, representing the contents of a subdirectory. Since trees
2847
+and blobs, like all other objects, are named by the SHA1 hash of their
2848
+contents, two trees have the same SHA1 name if and only if their
2849
+contents (including, recursively, the contents of all subdirectories)
2850
+are identical. This allows git to quickly determine the differences
2851
+between two related tree objects, since it can ignore any entries with
2852
+identical object names.
2853
+
2854
+(Note: in the presence of submodules, trees may also have commits as
2855
+entries. See gitlink:git-submodule[1] and gitlink:gitmodules.txt[1]
2856
+for partial documentation.)
2857
+
2858
+Note that the files all have mode 644 or 755: git actually only pays
2859
+attention to the executable bit.
2860
2861
[[blob-object]]
2862
Blob Object
2863
~~~~~~~~~~~
2864
2842
-A "blob" object is nothing but a binary blob of data, and doesn't
2843
-refer to anything else. There is no signature or any other
2844
-verification of the data, so while the object is consistent (it 'is'
2845
-indexed by its sha1 hash, so the data itself is certainly correct), it
2846
-has absolutely no other attributes. No name associations, no
2847
-permissions. It is purely a blob of data (i.e. normally "file
2848
-contents").
2865
+You can use gitlink:git-show[1] to examine the contents of a blob; take,
2866
+for example, the blob in the entry for "COPYING" from the tree above:
2867
+
2868
+------------------------------------------------
2869
+$ git show 6ff87c4664
2870
+
2871
+ Note that the only valid version of the GPL as far as this project
2872
+ is concerned is _this_ particular version of the license (ie v2, not
2873
+ v2.2 or v3.x or whatever), unless explicitly otherwise stated.
2874
+...
2875
+------------------------------------------------
2876
2850
-In particular, since the blob is entirely defined by its data, if two
2851
-files in a directory tree (or in multiple different versions of the
2852
-repository) have the same contents, they will share the same blob
2853
-object. The object is totally independent of its location in the
2854
-directory tree, and renaming a file does not change the object that
2855
-file is associated with in any way.
2877
+A "blob" object is nothing but a binary blob of data. It doesn't refer
2878
+to anything else or have attributes of any kind.
2879
2857
-A blob is typically created when gitlink:git-update-index[1]
2858
-is run, and its data can be accessed by gitlink:git-cat-file[1].
2880
+Since the blob is entirely defined by its data, if two files in a
2881
+directory tree (or in multiple different versions of the repository)
2882
+have the same contents, they will share the same blob object. The object
2883
+is totally independent of its location in the directory tree, and
2884
+renaming a file does not change the object that file is associated with.
2885
+
2886
+Note that any tree or blob object can be examined using
2887
+gitlink:git-show[1] with the <revision>:<path> syntax. This can
2888
+sometimes be useful for browsing the contents of a tree that is not
2889
+currently checked out.
2890
2891
[[trust]]
2892
Trust
2893
~~~~~
2894
2864
-An aside on the notion of "trust". Trust is really outside the scope
2865
-of "git", but it's worth noting a few things. First off, since
2866
-everything is hashed with SHA1, you 'can' trust that an object is
2867
-intact and has not been messed with by external sources. So the name
2868
-of an object uniquely identifies a known state - just not a state that
2869
-you may want to trust.
2895
+If you receive the SHA1 name of a blob from one source, and its contents
2896
+from another (possibly untrusted) source, you can still trust that those
2897
+contents are correct as long as the SHA1 name agrees. This is because
2898
+the SHA1 is designed so that it is infeasible to find different contents
2899
+that produce the same hash.
2900
2871
-Furthermore, since the SHA1 signature of a commit refers to the
2872
-SHA1 signatures of the tree it is associated with and the signatures
2873
-of the parent, a single named commit specifies uniquely a whole set
2874
-of history, with full contents. You can't later fake any step of the
2875
-way once you have the name of a commit.
2901
+Similarly, you need only trust the SHA1 name of a top-level tree object
2902
+to trust the contents of the entire directory that it refers to, and if
2903
+you receive the SHA1 name of a commit from a trusted source, then you
2904
+can easily verify the entire history of commits reachable through
2905
+parents of that commit, and all of those contents of the trees referred
2906
+to by those commits.
2907
2908
So to introduce some real trust in the system, the only thing you need
2909
to do is to digitally sign just 'one' special note, which includes the
@@ -2891,23 +2922,31 @@ To assist in this, git also provides the tag object...
2922
Tag Object
2923
~~~~~~~~~~
2924
2894
-Git provides the "tag" object to simplify creating, managing and
2895
-exchanging symbolic and signed tokens. The "tag" object at its
2896
-simplest simply symbolically identifies another object by containing
2897
-the sha1, type and symbolic name.
2898
-
2899
-However it can optionally contain additional signature information
2900
-(which git doesn't care about as long as there's less than 8k of
2901
-it). This can then be verified externally to git.
2925
+A tag object contains an object, object type, tag name, the name of the
2926
+person ("tagger") who created the tag, and a message, which may contain
2927
+a signature, as can be seen using the gitlink:git-cat-file[1]:
2928
2903
-Note that despite the tag features, "git" itself only handles content
2904
-integrity; the trust framework (and signature provision and
2905
-verification) has to come from outside.
2929
+------------------------------------------------
2930
+$ git cat-file tag v1.5.0
2931
+object 437b1b20df4b356c9342dac8d38849f24ef44f27
2932
+type commit
2933
+tag v1.5.0
2934
+tagger Junio C Hamano <junkio@cox.net> 1171411200 +0000
2935
+
2936
+GIT 1.5.0
2937
+-----BEGIN PGP SIGNATURE-----
2938
+Version: GnuPG v1.4.6 (GNU/Linux)
2939
+
2940
+iD8DBQBF0lGqwMbZpPMRm5oRAuRiAJ9ohBLd7s2kqjkKlq1qqC57SbnmzQCdG4ui
2941
+nLE/L9aUXdWeTFPron96DLA=
2942
+=2E+0
2943
+-----END PGP SIGNATURE-----
2944
+------------------------------------------------
2945
2907
-A tag is created with gitlink:git-mktag[1],
2908
-its data can be accessed by gitlink:git-cat-file[1],
2909
-and the signature can be verified by
2910
-gitlink:git-verify-tag[1].
2946
+See the gitlink:git-tag[1] command to learn how to create and verify tag
2947
+objects. (Note that gitlink:git-tag[1] can also be used to create
2948
+"lightweight tags", which are not tag objects at all, but just simple
2949
+references in .git/refs/tags/).
2950
2951
2952
[[the-index]]
@@ -2978,6 +3017,24 @@ scripts using a smaller core of low-level git commands. These can still
3017
be useful when doing unusual things with git, or just as a way to
3018
understand its inner workings.
3019
3020
+[[object-manipulation]]
3021
+Object access and manipulation
3022
+------------------------------
3023
+
3024
+The gitlink:git-cat-file[1] command can show the contents of any object,
3025
+though the higher-level gitlink:git-show[1] is usually more useful.
3026
+
3027
+The gitlink:git-commit-tree[1] command allows constructing commits with
3028
+arbitrary parents and trees.
3029
+
3030
+A tree can be created with gitlink:git-write-tree[1] and its data can be
3031
+accessed by gitlink:git-ls-tree[1]. Two trees can be compared with
3032
+gitlink:git-diff-tree[1].
3033
+
3034
+A tag is created with gitlink:git-mktag[1], and the signature can be
3035
+verified by gitlink:git-verify-tag[1], though it is normally simpler to
3036
+use gitlink:git-tag[1] for both.
3037
+
3038
[[the-workflow]]
3039
The Workflow
3040
------------