[PATCH] Docs - asciidoc changes
Whitespace and asciidoc formatting changes only in preparation for content changes. Signed-off-by: David Greaves <david@dgreaves.com> Signed-off-by: Linus Torvalds <torvalds@osdl.org>
This commit is contained in:
parent
b2bf34d6c5
commit
8ac866a869
540
README
540
README
@ -1,9 +1,8 @@
|
|||||||
|
////////////////////////////////////////////////////////////////
|
||||||
|
|
||||||
|
|
||||||
GIT - the stupid content tracker
|
GIT - the stupid content tracker
|
||||||
|
|
||||||
|
////////////////////////////////////////////////////////////////
|
||||||
"git" can mean anything, depending on your mood.
|
"git" can mean anything, depending on your mood.
|
||||||
|
|
||||||
- random three-letter combination that is pronounceable, and not
|
- random three-letter combination that is pronounceable, and not
|
||||||
@ -22,16 +21,13 @@ contents efficiently.
|
|||||||
There are two object abstractions: the "object database", and the
|
There are two object abstractions: the "object database", and the
|
||||||
"current directory cache" aka "index".
|
"current directory cache" aka "index".
|
||||||
|
|
||||||
|
The Object Database
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
The Object Database (GIT_OBJECT_DIRECTORY)
|
|
||||||
|
|
||||||
|
|
||||||
The object database is literally just a content-addressable collection
|
The object database is literally just a content-addressable collection
|
||||||
of objects. All objects are named by their content, which is
|
of objects. All objects are named by their content, which is
|
||||||
approximated by the SHA1 hash of the object itself. Objects may refer
|
approximated by the SHA1 hash of the object itself. Objects may refer
|
||||||
to other objects (by referencing their SHA1 hash), and so you can build
|
to other objects (by referencing their SHA1 hash), and so you can
|
||||||
up a hierarchy of objects.
|
build up a hierarchy of objects.
|
||||||
|
|
||||||
All objects have a statically determined "type" aka "tag", which is
|
All objects have a statically determined "type" aka "tag", which is
|
||||||
determined at object creation time, and which identifies the format of
|
determined at object creation time, and which identifies the format of
|
||||||
@ -62,12 +58,17 @@ has two or more separate roots as its ultimate parents, that's probably
|
|||||||
just going to confuse people. So aim for the notion of "one root object
|
just going to confuse people. So aim for the notion of "one root object
|
||||||
per project", even if git itself does not enforce that.
|
per project", even if git itself does not enforce that.
|
||||||
|
|
||||||
|
A "tag" object symbolically identifies and can be used to sign other
|
||||||
|
objects. It contains the identifier and type of another object, a
|
||||||
|
symbolic name (of course!) and, optionally, a signature.
|
||||||
|
|
||||||
Regardless of object type, all objects are share the following
|
Regardless of object type, all objects are share the following
|
||||||
characteristics: they are all in deflated with zlib, and have a header
|
characteristics: they are all in deflated with zlib, and have a header
|
||||||
that not only specifies their tag, but also size information about the
|
that not only specifies their tag, but also size information about the
|
||||||
data in the object. It's worth noting that the SHA1 hash that is used
|
data in the object. It's worth noting that the SHA1 hash that is used
|
||||||
to name the object is always the hash of this _compressed_ object, not
|
to name the object is the hash of the original data (historical note:
|
||||||
the original data.
|
in the dawn of the age of git this was the sha1 of the _compressed_
|
||||||
|
object)
|
||||||
|
|
||||||
As a result, the general consistency of an object can always be tested
|
As a result, the general consistency of an object can always be tested
|
||||||
independently of the contents or the type of the object: all objects can
|
independently of the contents or the type of the object: all objects can
|
||||||
@ -76,157 +77,162 @@ file and (b) the object successfully inflates to a stream of bytes that
|
|||||||
forms a sequence of <ascii tag without space> + <space> + <ascii decimal
|
forms a sequence of <ascii tag without space> + <space> + <ascii decimal
|
||||||
size> + <byte\0> + <binary object data>.
|
size> + <byte\0> + <binary object data>.
|
||||||
|
|
||||||
The structured objects can further have their structure and connectivity
|
The structured objects can further have their structure and
|
||||||
to other objects verified. This is generally done with the "fsck-cache"
|
connectivity to other objects verified. This is generally done with
|
||||||
program, which generates a full dependency graph of all objects, and
|
the "fsck-cache" program, which generates a full dependency graph of
|
||||||
verifies their internal consistency (in addition to just verifying their
|
all objects, and verifies their internal consistency (in addition to
|
||||||
superficial consistency through the hash).
|
just verifying their superficial consistency through the hash).
|
||||||
|
|
||||||
The object types in some more detail:
|
The object types in some more detail:
|
||||||
|
|
||||||
BLOB: A "blob" object is nothing but a binary blob of data, and
|
Blob Object
|
||||||
doesn't refer to anything else. There is no signature or any
|
~~~~~~~~~~~
|
||||||
other verification of the data, so while the object is
|
A "blob" object is nothing but a binary blob of data, and doesn't
|
||||||
consistent (it _is_ indexed by its sha1 hash, so the data itself
|
refer to anything else. There is no signature or any other
|
||||||
is certainly correct), it has absolutely no other attributes.
|
verification of the data, so while the object is consistent (it _is_
|
||||||
No name associations, no permissions. It is purely a blob of
|
indexed by its sha1 hash, so the data itself is certainly correct), it
|
||||||
data (i.e. normally "file contents").
|
has absolutely no other attributes. No name associations, no
|
||||||
|
permissions. It is purely a blob of data (i.e. normally "file
|
||||||
|
contents").
|
||||||
|
|
||||||
In particular, since the blob is entirely defined by its data,
|
In particular, since the blob is entirely defined by its data, if two
|
||||||
if two files in a directory tree (or in multiple different
|
files in a directory tree (or in multiple different versions of the
|
||||||
versions of the repository) have the same contents, they will
|
repository) have the same contents, they will share the same blob
|
||||||
share the same blob object. The object is totally independent
|
object. The object is totally independent of it's location in the
|
||||||
of it's location in the directory tree, and renaming a file does
|
directory tree, and renaming a file does not change the object that
|
||||||
not change the object that file is associated with in any way.
|
file is associated with in any way.
|
||||||
|
|
||||||
TREE: The next hierarchical object type is the "tree" object. A tree
|
Tree Object
|
||||||
object is a list of mode/name/blob data, sorted by name.
|
~~~~~~~~~~~
|
||||||
Alternatively, the mode data may specify a directory mode, in
|
The next hierarchical object type is the "tree" object. A tree object
|
||||||
which case instead of naming a blob, that name is associated
|
is a list of mode/name/blob data, sorted by name. Alternatively, the
|
||||||
with another TREE object.
|
mode data may specify a directory mode, in which case instead of
|
||||||
|
naming a blob, that name is associated with another TREE object.
|
||||||
|
|
||||||
Like the "blob" object, a tree object is uniquely determined by
|
Like the "blob" object, a tree object is uniquely determined by the
|
||||||
the set contents, and so two separate but identical trees will
|
set contents, and so two separate but identical trees will always
|
||||||
always share the exact same object. This is true at all levels,
|
share the exact same object. This is true at all levels, i.e. it's
|
||||||
i.e. it's true for a "leaf" tree (which does not refer to any
|
true for a "leaf" tree (which does not refer to any other trees, only
|
||||||
other trees, only blobs) as well as for a whole subdirectory.
|
blobs) as well as for a whole subdirectory.
|
||||||
|
|
||||||
For that reason a "tree" object is just a pure data abstraction:
|
For that reason a "tree" object is just a pure data abstraction: it
|
||||||
it has no history, no signatures, no verification of validity,
|
has no history, no signatures, no verification of validity, except
|
||||||
except that since the contents are again protected by the hash
|
that since the contents are again protected by the hash itself, we can
|
||||||
itself, we can trust that the tree is immutable and its contents
|
trust that the tree is immutable and its contents never change.
|
||||||
never change.
|
|
||||||
|
|
||||||
So you can trust the contents of a tree to be valid, the same
|
So you can trust the contents of a tree to be valid, the same way you
|
||||||
way you can trust the contents of a blob, but you don't know
|
can trust the contents of a blob, but you don't know where those
|
||||||
where those contents _came_ from.
|
contents _came_ from.
|
||||||
|
|
||||||
Side note on trees: since a "tree" object is a sorted list of
|
Side note on trees: since a "tree" object is a sorted list of
|
||||||
"filename+content", you can create a diff between two trees
|
"filename+content", you can create a diff between two trees without
|
||||||
without actually having to unpack two trees. Just ignore all
|
actually having to unpack two trees. Just ignore all common parts,
|
||||||
common parts, and your diff will look right. In other words,
|
and your diff will look right. In other words, you can effectively
|
||||||
you can effectively (and efficiently) tell the difference
|
(and efficiently) tell the difference between any two random trees by
|
||||||
between any two random trees by O(n) where "n" is the size of
|
O(n) where "n" is the size of the difference, rather than the size of
|
||||||
the difference, rather than the size of the tree.
|
the tree.
|
||||||
|
|
||||||
Side note 2 on trees: since the name of a "blob" depends
|
Side note 2 on trees: since the name of a "blob" depends entirely and
|
||||||
entirely and exclusively on its contents (i.e. there are no names
|
exclusively on its contents (i.e. there are no names or permissions
|
||||||
or permissions involved), you can see trivial renames or
|
involved), you can see trivial renames or permission changes by
|
||||||
permission changes by noticing that the blob stayed the same.
|
noticing that the blob stayed the same. However, renames with data
|
||||||
However, renames with data changes need a smarter "diff" implementation.
|
changes need a smarter "diff" implementation.
|
||||||
|
|
||||||
CHANGESET: The "changeset" object is an object that introduces the
|
|
||||||
notion of history into the picture. In contrast to the other
|
|
||||||
objects, it doesn't just describe the physical state of a tree,
|
|
||||||
it describes how we got there, and why.
|
|
||||||
|
|
||||||
A "changeset" is defined by the tree-object that it results in,
|
Changeset Object
|
||||||
the parent changesets (zero, one or more) that led up to that
|
~~~~~~~~~~~~~~~~
|
||||||
point, and a comment on what happened. Again, a changeset is
|
The "changeset" object is an object that introduces the notion of
|
||||||
not trusted per se: the contents are well-defined and "safe" due
|
history into the picture. In contrast to the other objects, it
|
||||||
to the cryptographically strong signatures at all levels, but
|
doesn't just describe the physical state of a tree, it describes how
|
||||||
there is no reason to believe that the tree is "good" or that
|
we got there, and why.
|
||||||
the merge information makes sense. The parents do not have to
|
|
||||||
actually have any relationship with the result, for example.
|
|
||||||
|
|
||||||
Note on changesets: unlike real SCM's, changesets do not contain
|
A "changeset" is defined by the tree-object that it results in, the
|
||||||
rename information or file mode change information. All of that
|
parent changesets (zero, one or more) that led up to that point, and a
|
||||||
is implicit in the trees involved (the result tree, and the
|
comment on what happened. Again, a changeset is not trusted per se:
|
||||||
result trees of the parents), and describing that makes no sense
|
the contents are well-defined and "safe" due to the cryptographically
|
||||||
in this idiotic file manager.
|
strong signatures at all levels, but there is no reason to believe
|
||||||
|
that the tree is "good" or that the merge information makes sense.
|
||||||
|
The parents do not have to actually have any relationship with the
|
||||||
|
result, for example.
|
||||||
|
|
||||||
TRUST: The notion of "trust" is really outside the scope of "git", but
|
Note on changesets: unlike real SCM's, changesets do not contain
|
||||||
it's worth noting a few things. First off, since everything is
|
rename information or file mode change information. All of that is
|
||||||
hashed with SHA1, you _can_ trust that an object is intact and
|
implicit in the trees involved (the result tree, and the result trees
|
||||||
has not been messed with by external sources. So the name of an
|
of the parents), and describing that makes no sense in this idiotic
|
||||||
object uniquely identifies a known state - just not a state that
|
file manager.
|
||||||
you may want to trust.
|
|
||||||
|
|
||||||
Furthermore, since the SHA1 signature of a changeset refers to
|
Trust Object
|
||||||
the SHA1 signatures of the tree it is associated with and the
|
~~~~~~~~~~~~
|
||||||
signatures of the parent, a single named changeset specifies
|
The notion of "trust" is really outside the scope of "git", but it's
|
||||||
uniquely a whole set of history, with full contents. You can't
|
worth noting a few things. First off, since everything is hashed with
|
||||||
later fake any step of the way once you have the name of a
|
SHA1, you _can_ trust that an object is intact and has not been messed
|
||||||
changeset.
|
with by external sources. So the name of an object uniquely
|
||||||
|
identifies a known state - just not a state that you may want to
|
||||||
|
trust.
|
||||||
|
|
||||||
So to introduce some real trust in the system, the only thing
|
Furthermore, since the SHA1 signature of a changeset refers to the
|
||||||
you need to do is to digitally sign just _one_ special note,
|
SHA1 signatures of the tree it is associated with and the signatures
|
||||||
which includes the name of a top-level changeset. Your digital
|
of the parent, a single named changeset specifies uniquely a whole set
|
||||||
signature shows others that you trust that changeset, and the
|
of history, with full contents. You can't later fake any step of the
|
||||||
immutability of the history of changesets tells others that they
|
way once you have the name of a changeset.
|
||||||
can trust the whole history.
|
|
||||||
|
|
||||||
In other words, you can easily validate a whole archive by just
|
So to introduce some real trust in the system, the only thing you need
|
||||||
sending out a single email that tells the people the name (SHA1
|
to do is to digitally sign just _one_ special note, which includes the
|
||||||
hash) of the top changeset, and digitally sign that email using
|
name of a top-level changeset. Your digital signature shows others
|
||||||
something like GPG/PGP.
|
that you trust that changeset, and the immutability of the history of
|
||||||
|
changesets tells others that they can trust the whole history.
|
||||||
|
|
||||||
In particular, you can also have a separate archive of "trust
|
In other words, you can easily validate a whole archive by just
|
||||||
points" or tags, which document your (and other peoples) trust.
|
sending out a single email that tells the people the name (SHA1 hash)
|
||||||
You may, of course, archive these "certificates of trust" using
|
of the top changeset, and digitally sign that email using something
|
||||||
"git" itself, but it's not something "git" does for you.
|
like GPG/PGP.
|
||||||
|
|
||||||
Another way of saying the last point: "git" itself only handles content
|
In particular, you can also have a separate archive of "trust points"
|
||||||
integrity, the trust has to come from outside.
|
or tags, which document your (and other peoples) trust. You may, of
|
||||||
|
course, archive these "certificates of trust" using "git" itself, but
|
||||||
|
it's not something "git" does for you.
|
||||||
|
|
||||||
|
Another way of saying the last point: "git" itself only handles
|
||||||
|
content integrity, the trust has to come from outside.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
The "index" aka "Current Directory Cache" (".git/index")
|
|
||||||
|
|
||||||
|
|
||||||
|
The "index" aka "Current Directory Cache"
|
||||||
|
-----------------------------------------
|
||||||
The index is a simple binary file, which contains an efficient
|
The index is a simple binary file, which contains an efficient
|
||||||
representation of a virtual directory content at some random time. It
|
representation of a virtual directory content at some random time. It
|
||||||
does so by a simple array that associates a set of names, dates,
|
does so by a simple array that associates a set of names, dates,
|
||||||
permissions and content (aka "blob") objects together. The cache is
|
permissions and content (aka "blob") objects together. The cache is
|
||||||
always kept ordered by name, and names are unique (with a few very
|
always kept ordered by name, and names are unique (with a few very
|
||||||
specific rules) at any point in time, but the cache has no long-term
|
specific rules) at any point in time, but the cache has no long-term
|
||||||
meaning, and can be partially updated at any time.
|
meaning, and can be partially updated at any time.
|
||||||
|
|
||||||
In particular, the index certainly does not need to be consistent with
|
In particular, the index certainly does not need to be consistent with
|
||||||
the current directory contents (in fact, most operations will depend on
|
the current directory contents (in fact, most operations will depend on
|
||||||
different ways to make the index _not_ be consistent with the directory
|
different ways to make the index _not_ be consistent with the directory
|
||||||
hierarchy), but it has three very important attributes:
|
hierarchy), but it has three very important attributes:
|
||||||
|
|
||||||
(a) it can re-generate the full state it caches (not just the directory
|
'(a) it can re-generate the full state it caches (not just the
|
||||||
structure: it contains pointers to the "blob" objects so that it
|
directory structure: it contains pointers to the "blob" objects so
|
||||||
can regenerate the data too)
|
that it can regenerate the data too)'
|
||||||
|
|
||||||
As a special case, there is a clear and unambiguous one-way mapping
|
As a special case, there is a clear and unambiguous one-way mapping
|
||||||
from a current directory cache to a "tree object", which can be
|
from a current directory cache to a "tree object", which can be
|
||||||
efficiently created from just the current directory cache without
|
efficiently created from just the current directory cache without
|
||||||
actually looking at any other data. So a directory cache at any
|
actually looking at any other data. So a directory cache at any one
|
||||||
one time uniquely specifies one and only one "tree" object (but
|
time uniquely specifies one and only one "tree" object (but has
|
||||||
has additional data to make it easy to match up that tree object
|
additional data to make it easy to match up that tree object with what
|
||||||
with what has happened in the directory)
|
has happened in the directory)
|
||||||
|
|
||||||
(b) it has efficient methods for finding inconsistencies between that
|
'(b) it has efficient methods for finding inconsistencies between that
|
||||||
cached state ("tree object waiting to be instantiated") and the
|
cached state ("tree object waiting to be instantiated") and the
|
||||||
current state.
|
current state.'
|
||||||
|
|
||||||
(c) it can additionally efficiently represent information about merge
|
'(c) it can additionally efficiently represent information about merge
|
||||||
conflicts between different tree objects, allowing each pathname to
|
conflicts between different tree objects, allowing each pathname to be
|
||||||
be associated with sufficient information about the trees involved
|
associated with sufficient information about the trees involved that
|
||||||
that you can create a three-way merge between them.
|
you can create a three-way merge between them.'
|
||||||
|
|
||||||
Those are the three ONLY things that the directory cache does. It's a
|
Those are the three ONLY things that the directory cache does. It's a
|
||||||
cache, and the normal operation is to re-generate it completely from a
|
cache, and the normal operation is to re-generate it completely from a
|
||||||
@ -241,220 +247,216 @@ involves a controlled modification of the index file. In particular,
|
|||||||
the index file can have the representation of an intermediate tree that
|
the index file can have the representation of an intermediate tree that
|
||||||
has not yet been instantiated. So the index can be thought of as a
|
has not yet been instantiated. So the index can be thought of as a
|
||||||
write-back cache, which can contain dirty information that has not yet
|
write-back cache, which can contain dirty information that has not yet
|
||||||
been written back to the backing store.
|
been written back to the backing store.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
The Workflow
|
The Workflow
|
||||||
|
------------
|
||||||
|
|
||||||
Generally, all "git" operations work on the index file. Some operations
|
Generally, all "git" operations work on the index file. Some operations
|
||||||
work _purely_ on the index file (showing the current state of the
|
work *purely* on the index file (showing the current state of the
|
||||||
index), but most operations move data to and from the index file. Either
|
index), but most operations move data to and from the index file. Either
|
||||||
from the database or from the working directory. Thus there are four
|
from the database or from the working directory. Thus there are four
|
||||||
main combinations:
|
main combinations:
|
||||||
|
|
||||||
1) working directory -> index
|
1) working directory -> index
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
You update the index with information from the working directory
|
You update the index with information from the working directory with
|
||||||
with the "update-cache" command. You generally update the index
|
the "update-cache" command. You generally update the index
|
||||||
information by just specifying the filename you want to update,
|
information by just specifying the filename you want to update, like
|
||||||
like so:
|
so:
|
||||||
|
|
||||||
update-cache filename
|
update-cache filename
|
||||||
|
|
||||||
but to avoid common mistakes with filename globbing etc, the
|
but to avoid common mistakes with filename globbing etc, the command
|
||||||
command will not normally add totally new entries or remove old
|
will not normally add totally new entries or remove old entries,
|
||||||
entries, i.e. it will normally just update existing cache entries.
|
i.e. it will normally just update existing cache entries.
|
||||||
|
|
||||||
To tell git that yes, you really do realize that certain files
|
To tell git that yes, you really do realize that certain files no
|
||||||
no longer exist in the archive, or that new files should be
|
longer exist in the archive, or that new files should be added, you
|
||||||
added, you should use the "--remove" and "--add" flags
|
should use the "--remove" and "--add" flags respectively.
|
||||||
respectively.
|
|
||||||
|
|
||||||
NOTE! A "--remove" flag does _not_ mean that subsequent
|
NOTE! A "--remove" flag does _not_ mean that subsequent filenames will
|
||||||
filenames will necessarily be removed: if the files still exist
|
necessarily be removed: if the files still exist in your directory
|
||||||
in your directory structure, the index will be updated with
|
structure, the index will be updated with their new status, not
|
||||||
their new status, not removed. The only thing "--remove" means
|
removed. The only thing "--remove" means is that update-cache will be
|
||||||
is that update-cache will be considering a removed file to be a
|
considering a removed file to be a valid thing, and if the file really
|
||||||
valid thing, and if the file really does not exist any more, it
|
does not exist any more, it will update the index accordingly.
|
||||||
will update the index accordingly.
|
|
||||||
|
|
||||||
As a special case, you can also do "update-cache --refresh",
|
As a special case, you can also do "update-cache --refresh", which
|
||||||
which will refresh the "stat" information of each index to match
|
will refresh the "stat" information of each index to match the current
|
||||||
the current stat information. It will _not_ update the object
|
stat information. It will _not_ update the object status itself, and
|
||||||
status itself, and it will only update the fields that are used
|
it will only update the fields that are used to quickly test whether
|
||||||
to quickly test whether an object still matches its old backing
|
an object still matches its old backing store object.
|
||||||
store object.
|
|
||||||
|
|
||||||
2) index -> object database
|
2) index -> object database
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
You write your current index file to a "tree" object with the
|
You write your current index file to a "tree" object with the program
|
||||||
program
|
|
||||||
|
|
||||||
write-tree
|
write-tree
|
||||||
|
|
||||||
that doesn't come with any options - it will just write out the
|
that doesn't come with any options - it will just write out the
|
||||||
current index into the set of tree objects that describe that
|
current index into the set of tree objects that describe that state,
|
||||||
state, and it will return the name of the resulting top-level
|
and it will return the name of the resulting top-level tree. You can
|
||||||
tree. You can use that tree to re-generate the index at any time
|
use that tree to re-generate the index at any time by going in the
|
||||||
by going in the other direction:
|
other direction:
|
||||||
|
|
||||||
3) object database -> index
|
3) object database -> index
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
You read a "tree" file from the object database, and use that to
|
You read a "tree" file from the object database, and use that to
|
||||||
populate (and overwrite - don't do this if your index contains
|
populate (and overwrite - don't do this if your index contains any
|
||||||
any unsaved state that you might want to restore later!) your
|
unsaved state that you might want to restore later!) your current
|
||||||
current index. Normal operation is just
|
index. Normal operation is just
|
||||||
|
|
||||||
read-tree <sha1 of tree>
|
read-tree <sha1 of tree>
|
||||||
|
|
||||||
and your index file will now be equivalent to the tree that you
|
and your index file will now be equivalent to the tree that you saved
|
||||||
saved earlier. However, that is only your _index_ file: your
|
earlier. However, that is only your _index_ file: your working
|
||||||
working directory contents have not been modified.
|
directory contents have not been modified.
|
||||||
|
|
||||||
4) index -> working directory
|
4) index -> working directory
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
You update your working directory from the index by "checking
|
You update your working directory from the index by "checking out"
|
||||||
out" files. This is not a very common operation, since normally
|
files. This is not a very common operation, since normally you'd just
|
||||||
you'd just keep your files updated, and rather than write to
|
keep your files updated, and rather than write to your working
|
||||||
your working directory, you'd tell the index files about the
|
directory, you'd tell the index files about the changes in your
|
||||||
changes in your working directory (i.e. "update-cache").
|
working directory (i.e. "update-cache").
|
||||||
|
|
||||||
However, if you decide to jump to a new version, or check out
|
However, if you decide to jump to a new version, or check out somebody
|
||||||
somebody else's version, or just restore a previous tree, you'd
|
else's version, or just restore a previous tree, you'd populate your
|
||||||
populate your index file with read-tree, and then you need to
|
index file with read-tree, and then you need to check out the result
|
||||||
check out the result with
|
with
|
||||||
|
|
||||||
checkout-cache filename
|
checkout-cache filename
|
||||||
|
|
||||||
or, if you want to check out all of the index, use "-a".
|
or, if you want to check out all of the index, use "-a".
|
||||||
|
|
||||||
NOTE! checkout-cache normally refuses to overwrite old files, so
|
NOTE! checkout-cache normally refuses to overwrite old files, so if
|
||||||
if you have an old version of the tree already checked out, you
|
you have an old version of the tree already checked out, you will need
|
||||||
will need to use the "-f" flag (_before_ the "-a" flag or the
|
to use the "-f" flag (_before_ the "-a" flag or the filename) to
|
||||||
filename) to _force_ the checkout.
|
_force_ the checkout.
|
||||||
|
|
||||||
|
|
||||||
Finally, there are a few odds and ends which are not purely moving from
|
Finally, there are a few odds and ends which are not purely moving
|
||||||
one representation to the other:
|
from one representation to the other:
|
||||||
|
|
||||||
5) Tying it all together
|
5) Tying it all together
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
To commit a tree you have instantiated with "write-tree", you'd
|
To commit a tree you have instantiated with "write-tree", you'd create
|
||||||
create a "commit" object that refers to that tree and the
|
a "commit" object that refers to that tree and the history behind it -
|
||||||
history behind it - most notably the "parent" commits that
|
most notably the "parent" commits that preceded it in history.
|
||||||
preceded it in history.
|
|
||||||
|
|
||||||
Normally a "commit" has one parent: the previous state of the
|
Normally a "commit" has one parent: the previous state of the tree
|
||||||
tree before a certain change was made. However, sometimes it can
|
before a certain change was made. However, sometimes it can have two
|
||||||
have two or more parent commits, in which case we call it a
|
or more parent commits, in which case we call it a "merge", due to the
|
||||||
"merge", due to the fact that such a commit brings together
|
fact that such a commit brings together ("merges") two or more
|
||||||
("merges") two or more previous states represented by other
|
previous states represented by other commits.
|
||||||
commits.
|
|
||||||
|
|
||||||
In other words, while a "tree" represents a particular directory
|
In other words, while a "tree" represents a particular directory state
|
||||||
state of a working directory, a "commit" represents that state
|
of a working directory, a "commit" represents that state in "time",
|
||||||
in "time", and explains how we got there.
|
and explains how we got there.
|
||||||
|
|
||||||
You create a commit object by giving it the tree that describes
|
You create a commit object by giving it the tree that describes the
|
||||||
the state at the time of the commit, and a list of parents:
|
state at the time of the commit, and a list of parents:
|
||||||
|
|
||||||
commit-tree <tree> -p <parent> [-p <parent2> ..]
|
commit-tree <tree> -p <parent> [-p <parent2> ..]
|
||||||
|
|
||||||
and then giving the reason for the commit on stdin (either
|
and then giving the reason for the commit on stdin (either through
|
||||||
through redirection from a pipe or file, or by just typing it at
|
redirection from a pipe or file, or by just typing it at the tty).
|
||||||
the tty).
|
|
||||||
|
|
||||||
commit-tree will return the name of the object that represents
|
commit-tree will return the name of the object that represents that
|
||||||
that commit, and you should save it away for later use.
|
commit, and you should save it away for later use. Normally, you'd
|
||||||
Normally, you'd commit a new "HEAD" state, and while git doesn't
|
commit a new "HEAD" state, and while git doesn't care where you save
|
||||||
care where you save the note about that state, in practice we
|
the note about that state, in practice we tend to just write the
|
||||||
tend to just write the result to the file ".git/HEAD", so that
|
result to the file ".git/HEAD", so that we can always see what the
|
||||||
we can always see what the last committed state was.
|
last committed state was.
|
||||||
|
|
||||||
6) Examining the data
|
6) Examining the data
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
You can examine the data represented in the object database and
|
You can examine the data represented in the object database and the
|
||||||
the index with various helper tools. For every object, you can
|
index with various helper tools. For every object, you can use
|
||||||
use "cat-file" to examine details about the object:
|
"cat-file" to examine details about the object:
|
||||||
|
|
||||||
cat-file -t <objectname>
|
cat-file -t <objectname>
|
||||||
|
|
||||||
shows the type of the object, and once you have the type (which
|
shows the type of the object, and once you have the type (which is
|
||||||
is usually implicit in where you find the object), you can use
|
usually implicit in where you find the object), you can use
|
||||||
|
|
||||||
cat-file blob|tree|commit <objectname>
|
cat-file blob|tree|commit <objectname>
|
||||||
|
|
||||||
to show its contents. NOTE! Trees have binary content, and as a
|
to show its contents. NOTE! Trees have binary content, and as a result
|
||||||
result there is a special helper for showing that content,
|
there is a special helper for showing that content, called "ls-tree",
|
||||||
called "ls-tree", which turns the binary content into a more
|
which turns the binary content into a more easily readable form.
|
||||||
easily readable form.
|
|
||||||
|
|
||||||
It's especially instructive to look at "commit" objects, since
|
It's especially instructive to look at "commit" objects, since those
|
||||||
those tend to be small and fairly self-explanatory. In
|
tend to be small and fairly self-explanatory. In particular, if you
|
||||||
particular, if you follow the convention of having the top
|
follow the convention of having the top commit name in ".git/HEAD",
|
||||||
commit name in ".git/HEAD", you can do
|
you can do
|
||||||
|
|
||||||
cat-file commit $(cat .git/HEAD)
|
cat-file commit $(cat .git/HEAD)
|
||||||
|
|
||||||
to see what the top commit was.
|
to see what the top commit was.
|
||||||
|
|
||||||
7) Merging multiple trees
|
7) Merging multiple trees
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
Git helps you do a three-way merge, which you can expand to
|
Git helps you do a three-way merge, which you can expand to n-way by
|
||||||
n-way by repeating the merge procedure arbitrary times until you
|
repeating the merge procedure arbitrary times until you finally
|
||||||
finally "commit" the state. The normal situation is that you'd
|
"commit" the state. The normal situation is that you'd only do one
|
||||||
only do one three-way merge (two parents), and commit it, but if
|
three-way merge (two parents), and commit it, but if you like to, you
|
||||||
you like to, you can do multiple parents in one go.
|
can do multiple parents in one go.
|
||||||
|
|
||||||
To do a three-way merge, you need the two sets of "commit"
|
To do a three-way merge, you need the two sets of "commit" objects
|
||||||
objects that you want to merge, use those to find the closest
|
that you want to merge, use those to find the closest common parent (a
|
||||||
common parent (a third "commit" object), and then use those
|
third "commit" object), and then use those commit objects to find the
|
||||||
commit objects to find the state of the directory ("tree"
|
state of the directory ("tree" object) at these points.
|
||||||
object) at these points.
|
|
||||||
|
|
||||||
To get the "base" for the merge, you first look up the common
|
To get the "base" for the merge, you first look up the common parent
|
||||||
parent of two commits with
|
of two commits with
|
||||||
|
|
||||||
merge-base <commit1> <commit2>
|
merge-base <commit1> <commit2>
|
||||||
|
|
||||||
which will return you the commit they are both based on. You
|
which will return you the commit they are both based on. You should
|
||||||
should now look up the "tree" objects of those commits, which
|
now look up the "tree" objects of those commits, which you can easily
|
||||||
you can easily do with (for example)
|
do with (for example)
|
||||||
|
|
||||||
cat-file commit <commitname> | head -1
|
cat-file commit <commitname> | head -1
|
||||||
|
|
||||||
since the tree object information is always the first line in a
|
since the tree object information is always the first line in a commit
|
||||||
commit object.
|
object.
|
||||||
|
|
||||||
Once you know the three trees you are going to merge (the one
|
Once you know the three trees you are going to merge (the one
|
||||||
"original" tree, aka the common case, and the two "result" trees,
|
"original" tree, aka the common case, and the two "result" trees, aka
|
||||||
aka the branches you want to merge), you do a "merge" read into
|
the branches you want to merge), you do a "merge" read into the
|
||||||
the index. This will throw away your old index contents, so you
|
index. This will throw away your old index contents, so you should
|
||||||
should make sure that you've committed those - in fact you would
|
make sure that you've committed those - in fact you would normally
|
||||||
normally always do a merge against your last commit (which
|
always do a merge against your last commit (which should thus match
|
||||||
should thus match what you have in your current index anyway).
|
what you have in your current index anyway).
|
||||||
To do the merge, do
|
|
||||||
|
To do the merge, do
|
||||||
|
|
||||||
read-tree -m <origtree> <target1tree> <target2tree>
|
read-tree -m <origtree> <target1tree> <target2tree>
|
||||||
|
|
||||||
which will do all trivial merge operations for you directly in
|
which will do all trivial merge operations for you directly in the
|
||||||
the index file, and you can just write the result out with
|
index file, and you can just write the result out with "write-tree".
|
||||||
"write-tree".
|
|
||||||
|
|
||||||
NOTE! Because the merge is done in the index file, and not in
|
NOTE! Because the merge is done in the index file, and not in your
|
||||||
your working directory, your working directory will no longer
|
working directory, your working directory will no longer match your
|
||||||
match your index. You can use "checkout-cache -f -a" to make the
|
index. You can use "checkout-cache -f -a" to make the effect of the
|
||||||
effect of the merge be seen in your working directory.
|
merge be seen in your working directory.
|
||||||
|
|
||||||
NOTE2! Sadly, many merges aren't trivial. If there are files
|
NOTE2! Sadly, many merges aren't trivial. If there are files that have
|
||||||
that have been added.moved or removed, or if both branches have
|
been added.moved or removed, or if both branches have modified the
|
||||||
modified the same file, you will be left with an index tree that
|
same file, you will be left with an index tree that contains "merge
|
||||||
contains "merge entries" in it. Such an index tree can _NOT_ be
|
entries" in it. Such an index tree can _NOT_ be written out to a tree
|
||||||
written out to a tree object, and you will have to resolve any
|
object, and you will have to resolve any such merge clashes using
|
||||||
such merge clashes using other tools before you can write out
|
other tools before you can write out the result.
|
||||||
the result.
|
|
||||||
|
|
||||||
[ fixme: talk about resolving merges here ]
|
|
||||||
|
|
||||||
|
[ fixme: talk about resolving merges here ]
|
||||||
|
Loading…
Reference in New Issue
Block a user