Tutorial updates.
- Use "working tree", "object name", "repository" as the canonical term consistenly. - Start formatting tutorial with asciidoc. - Mention shared repository style of cooperation. - Update with some usability enhancements recently made, such as the "-m" flag to the "git commit" command. Signed-off-by: Junio C Hamano <junkio@cox.net>
This commit is contained in:
Junio C Hamano
parent
0a5a9ea433
commit
2a29da7c6d
@ -1,8 +1,9 @@
|
||||
MAN1_TXT=$(wildcard git-*.txt)
|
||||
MAN7_TXT=git.txt
|
||||
|
||||
DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) glossary.html
|
||||
|
||||
DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT))
|
||||
DOC_HTML += glossary.html
|
||||
DOC_HTML += tutorial.html
|
||||
DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT))
|
||||
DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT))
|
||||
|
||||
@ -59,3 +60,5 @@ glossary.html : glossary.txt sort_glossary.pl
|
||||
perl sort_glossary.pl | \
|
||||
asciidoc -b xhtml11 - > glossary.html
|
||||
|
||||
tutorial.html : tutorial.txt
|
||||
asciidoc -b xhtml11 tutorial.txt
|
||||
|
||||
@ -1,13 +1,12 @@
|
||||
A short git tutorial
|
||||
====================
|
||||
May 2005
|
||||
|
||||
v0.99.5, Aug 2005
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
This is trying to be a short tutorial on setting up and using a git
|
||||
archive, mainly because being hands-on and using explicit examples is
|
||||
repository, mainly because being hands-on and using explicit examples is
|
||||
often the best way of explaining what is going on.
|
||||
|
||||
In normal life, most people wouldn't use the "core" git programs
|
||||
@ -23,16 +22,16 @@ plumbing directly very often, but it can be good to know what the
|
||||
plumbing does for when the porcelain isn't flushing...
|
||||
|
||||
|
||||
Creating a git archive
|
||||
----------------------
|
||||
Creating a git repository
|
||||
-------------------------
|
||||
|
||||
Creating a new git archive couldn't be easier: all git archives start
|
||||
Creating a new git repository couldn't be easier: all git repositories start
|
||||
out empty, and the only thing you need to do is find yourself a
|
||||
subdirectory that you want to use as a working tree - either an empty
|
||||
one for a totally new project, or an existing working tree that you want
|
||||
to import into git.
|
||||
|
||||
For our first example, we're going to start a totally new archive from
|
||||
For our first example, we're going to start a totally new repository from
|
||||
scratch, with no pre-existing files, and we'll call it "git-tutorial".
|
||||
To start up, create a subdirectory for it, change into that
|
||||
subdirectory, and initialize the git infrastructure with "git-init-db":
|
||||
@ -49,7 +48,7 @@ which is just git's way of saying that you haven't been doing anything
|
||||
strange, and that it will have created a local .git directory setup for
|
||||
your new project. You will now have a ".git" directory, and you can
|
||||
inspect that with "ls". For your new empty project, ls should show you
|
||||
three entries:
|
||||
three entries, among other things:
|
||||
|
||||
- a symlink called HEAD, pointing to "refs/heads/master"
|
||||
|
||||
@ -57,7 +56,7 @@ three entries:
|
||||
doesn't even exist yet - you haven't created the commit that will
|
||||
start your HEAD development branch yet.
|
||||
|
||||
- a subdirectory called "objects", which will contain all the git SHA1
|
||||
- a subdirectory called "objects", which will contain all the
|
||||
objects of your project. You should never have any real reason to
|
||||
look at the objects directly, but you might want to know that these
|
||||
objects are what contains all the real _data_ in your repository.
|
||||
@ -68,7 +67,7 @@ three entries:
|
||||
subdirectories, named "heads" and "tags" respectively. They do
|
||||
exactly what their names imply: they contain references to any number
|
||||
of different "heads" of development (aka "branches"), and to any
|
||||
"tags" that you have created to name specific versions of your
|
||||
"tags" that you have created to name specific versions in your
|
||||
repository.
|
||||
|
||||
One note: the special "master" head is the default branch, which is
|
||||
@ -90,33 +89,33 @@ three entries:
|
||||
number of 41-byte files containing these references in this refs
|
||||
subdirectories when you actually start populating your tree ]
|
||||
|
||||
You have now created your first git archive. Of course, since it's
|
||||
You have now created your first git repository. Of course, since it's
|
||||
empty, that's not very useful, so let's start populating it with data.
|
||||
|
||||
|
||||
Populating a git archive
|
||||
------------------------
|
||||
Populating a git repository
|
||||
---------------------------
|
||||
|
||||
We'll keep this simple and stupid, so we'll start off with populating a
|
||||
few trivial files just to get a feel for it.
|
||||
|
||||
Start off with just creating any random files that you want to maintain
|
||||
in your git archive. We'll start off with a few bad examples, just to
|
||||
in your git repository. We'll start off with a few bad examples, just to
|
||||
get a feel for how this works:
|
||||
|
||||
echo "Hello World" >hello
|
||||
echo "Silly example" >example
|
||||
|
||||
you have now created two files in your working directory, but to
|
||||
you have now created two files in your working tree (aka "working directory"), but to
|
||||
actually check in your hard work, you will have to go through two steps:
|
||||
|
||||
- fill in the "cache" aka "index" file with the information about your
|
||||
working directory state
|
||||
- fill in the "index" file (aka "cache") with the information about your
|
||||
working tree state.
|
||||
|
||||
- commit that index file as an object.
|
||||
|
||||
The first step is trivial: when you want to tell git about any changes
|
||||
to your working directory, you use the "git-update-cache" program. That
|
||||
to your working tree, you use the "git-update-cache" program. That
|
||||
program normally just takes a list of filenames you want to update, but
|
||||
to avoid trivial mistakes, it refuses to add new entries to the cache
|
||||
(or remove existing ones) unless you explicitly tell it that you're
|
||||
@ -131,7 +130,7 @@ and you have now told git to track those two files.
|
||||
|
||||
In fact, as you did that, if you now look into your object directory,
|
||||
you'll notice that git will have added two new objects to the object
|
||||
store. If you did exactly the steps above, you should now be able to do
|
||||
database. If you did exactly the steps above, you should now be able to do
|
||||
|
||||
ls .git/objects/??/*
|
||||
|
||||
@ -140,7 +139,7 @@ and see two files:
|
||||
.git/objects/55/7db03de997c86a4a028e1ebd3a1ceb225be238
|
||||
.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
|
||||
|
||||
which correspond with the object with SHA1 names of 557db... and f24c7..
|
||||
which correspond with the objects with names of 557db... and f24c7..
|
||||
respectively.
|
||||
|
||||
If you want to, you can use "git-cat-file" to look at those objects, but
|
||||
@ -152,9 +151,9 @@ where the "-t" tells git-cat-file to tell you what the "type" of the
|
||||
object is. Git will tell you that you have a "blob" object (ie just a
|
||||
regular file), and you can see the contents with
|
||||
|
||||
git-cat-file "blob" 557db03de997c86a4a028e1ebd3a1ceb225be238
|
||||
git-cat-file "blob" 557db03
|
||||
|
||||
which will print out "Hello World". The object 557db... is nothing
|
||||
which will print out "Hello World". The object 557db03 is nothing
|
||||
more than the contents of your file "hello".
|
||||
|
||||
[ Digression: don't confuse that object with the file "hello" itself. The
|
||||
@ -162,12 +161,16 @@ more than the contents of your file "hello".
|
||||
however much you later change the contents in file "hello", the object we
|
||||
just looked at will never change. Objects are immutable. ]
|
||||
|
||||
[ Digression #2: the second example demonstrates that you can
|
||||
abbreviate the object name to only the first several
|
||||
hexadecimal digits in most places. ]
|
||||
|
||||
Anyway, as we mentioned previously, you normally never actually take a
|
||||
look at the objects themselves, and typing long 40-character hex SHA1
|
||||
look at the objects themselves, and typing long 40-character hex
|
||||
names is not something you'd normally want to do. The above digression
|
||||
was just to show that "git-update-cache" did something magical, and
|
||||
actually saved away the contents of your files into the git content
|
||||
store.
|
||||
actually saved away the contents of your files into the git object
|
||||
database.
|
||||
|
||||
Updating the cache did something else too: it created a ".git/index"
|
||||
file. This is the index that describes your current working tree, and
|
||||
@ -190,7 +193,7 @@ git what has changed in the tree compared to your old index, using the
|
||||
|
||||
git-diff-files
|
||||
|
||||
oops. That wasn't very readable. It just spit out its own internal
|
||||
Oops. That wasn't very readable. It just spit out its own internal
|
||||
version of a "diff", but that internal version really just tells you
|
||||
that it has noticed that "hello" has been modified, and that the old object
|
||||
contents it had have been replaced with something else.
|
||||
@ -222,8 +225,8 @@ A common shorthand for "git-diff-files -p" is to just write
|
||||
which will do the same thing.
|
||||
|
||||
|
||||
Committing git state
|
||||
--------------------
|
||||
Committing git state
|
||||
--------------------
|
||||
|
||||
Now, we want to go to the next stage in git, which is to take the files
|
||||
that git knows about in the index, and commit them as a real tree. We do
|
||||
@ -259,9 +262,9 @@ argument to "git-commit-tree".
|
||||
|
||||
"git-commit-tree" normally takes several arguments - it wants to know
|
||||
what the _parent_ of a commit was, but since this is the first commit
|
||||
ever in this new archive, and it has no parents, we only need to pass in
|
||||
the tree ID. However, git-commit-tree also wants to get a commit message
|
||||
on its standard input, and it will write out the resulting ID for the
|
||||
ever in this new repository, and it has no parents, we only need to pass in
|
||||
the object name of the tree. However, git-commit-tree also wants to get a commit message
|
||||
on its standard input, and it will write out the resulting object name for the
|
||||
commit to its standard output.
|
||||
|
||||
And this is where we start using the .git/HEAD file. The HEAD file is
|
||||
@ -290,8 +293,8 @@ you could have just written
|
||||
instead, and it would have done the above magic scripting for you.
|
||||
|
||||
|
||||
Making a change
|
||||
---------------
|
||||
Making a change
|
||||
---------------
|
||||
|
||||
Remember how we did the "git-update-cache" on file "hello" and then we
|
||||
changed "hello" afterward, and could compare the new state of "hello" with the
|
||||
@ -301,7 +304,7 @@ Further, remember how I said that "git-write-tree" writes the contents
|
||||
of the _index_ file to the tree, and thus what we just committed was in
|
||||
fact the _original_ contents of the file "hello", not the new ones. We did
|
||||
that on purpose, to show the difference between the index state, and the
|
||||
state in the working directory, and how they don't have to match, even
|
||||
state in the working tree, and how they don't have to match, even
|
||||
when we commit things.
|
||||
|
||||
As before, if we do "git-diff-files -p" in our git-tutorial project,
|
||||
@ -311,9 +314,9 @@ have committed something, we can also learn to use a new command:
|
||||
"git-diff-cache".
|
||||
|
||||
Unlike "git-diff-files", which showed the difference between the index
|
||||
file and the working directory, "git-diff-cache" shows the differences
|
||||
file and the working tree, "git-diff-cache" shows the differences
|
||||
between a committed _tree_ and either the index file or the working
|
||||
directory. In other words, git-diff-cache wants a tree to be diffed
|
||||
tree. In other words, git-diff-cache wants a tree to be diffed
|
||||
against, and before we did the commit, we couldn't do that, because we
|
||||
didn't have anything to diff against.
|
||||
|
||||
@ -323,7 +326,7 @@ But now we can do
|
||||
|
||||
(where "-p" has the same meaning as it did in git-diff-files), and it
|
||||
will show us the same difference, but for a totally different reason.
|
||||
Now we're comparing the working directory not against the index file,
|
||||
Now we're comparing the working tree not against the index file,
|
||||
but against the tree we just wrote. It just so happens that those two
|
||||
are obviously the same, so we get the same result.
|
||||
|
||||
@ -335,19 +338,19 @@ it with
|
||||
which ends up doing the above for you.
|
||||
|
||||
In other words, "git-diff-cache" normally compares a tree against the
|
||||
working directory, but when given the "--cached" flag, it is told to
|
||||
working tree, but when given the "--cached" flag, it is told to
|
||||
instead compare against just the index cache contents, and ignore the
|
||||
current working directory state entirely. Since we just wrote the index
|
||||
current working tree state entirely. Since we just wrote the index
|
||||
file to HEAD, doing "git-diff-cache --cached -p HEAD" should thus return
|
||||
an empty set of differences, and that's exactly what it does.
|
||||
|
||||
[ Digression: "git-diff-cache" really always uses the index for its
|
||||
comparisons, and saying that it compares a tree against the working
|
||||
directory is thus not strictly accurate. In particular, the list of
|
||||
tree is thus not strictly accurate. In particular, the list of
|
||||
files to compare (the "meta-data") _always_ comes from the index file,
|
||||
regardless of whether the --cached flag is used or not. The --cached
|
||||
flag really only determines whether the file _contents_ to be compared
|
||||
come from the working directory or not.
|
||||
come from the working tree or not.
|
||||
|
||||
This is not hard to understand, as soon as you realize that git simply
|
||||
never knows (or cares) about files that it is not told about
|
||||
@ -357,8 +360,8 @@ an empty set of differences, and that's exactly what it does.
|
||||
|
||||
However, our next step is to commit the _change_ we did, and again, to
|
||||
understand what's going on, keep in mind the difference between "working
|
||||
directory contents", "index file" and "committed tree". We have changes
|
||||
in the working directory that we want to commit, and we always have to
|
||||
tree contents", "index file" and "committed tree". We have changes
|
||||
in the working tree that we want to commit, and we always have to
|
||||
work through the index file, so the first thing we need to do is to
|
||||
update the index cache:
|
||||
|
||||
@ -372,7 +375,7 @@ we've updated "hello" in the index, "git-diff-files -p" now shows no
|
||||
differences, but "git-diff-cache -p HEAD" still _does_ show that the
|
||||
current state is different from the state we committed. In fact, now
|
||||
"git-diff-cache" shows the same difference whether we use the "--cached"
|
||||
flag or not, since now the index is coherent with the working directory.
|
||||
flag or not, since now the index is coherent with the working tree.
|
||||
|
||||
Now, since we've updated "hello" in the index, we can commit the new
|
||||
version. We could do it by writing the tree by hand again, and
|
||||
@ -384,7 +387,7 @@ already, so let's just use the helpful script this time:
|
||||
git commit
|
||||
|
||||
which starts an editor for you to write the commit message and tells you
|
||||
a bit about what you're doing.
|
||||
a bit about what you have done.
|
||||
|
||||
Write whatever message you want, and all the lines that start with '#'
|
||||
will be pruned out, and the rest will be used as the commit message for
|
||||
@ -399,8 +402,8 @@ it's a few very simple shell scripts to generate the helpful (?) commit
|
||||
message headers, and a few one-liners that actually do the commit itself.
|
||||
|
||||
|
||||
Checking it out
|
||||
---------------
|
||||
Checking it out
|
||||
---------------
|
||||
|
||||
While creating changes is useful, it's even more useful if you can tell
|
||||
later what changed. The most useful command for this is another of the
|
||||
@ -427,7 +430,7 @@ In fact, together with the "git-rev-list" program (which generates a
|
||||
list of revisions), git-diff-tree ends up being a veritable fount of
|
||||
changes. A trivial (but very useful) script called "git-whatchanged" is
|
||||
included with git which does exactly this, and shows a log of recent
|
||||
activity.
|
||||
activities.
|
||||
|
||||
To see the whole history of our pitiful little git-tutorial project, you
|
||||
can do
|
||||
@ -447,12 +450,11 @@ short history.
|
||||
show the initial aka "root" commit too. Normally you'd probably not
|
||||
want to see the initial import diff, but since the tutorial project
|
||||
was started from scratch and is so small, we use it to make the result
|
||||
a bit more interesting ]
|
||||
a bit more interesting. ]
|
||||
|
||||
With that, you should now be having some inkling of what git does, and
|
||||
can explore on your own.
|
||||
|
||||
|
||||
[ Side note: most likely, you are not directly using the core
|
||||
git Plumbing commands, but using Porcelain like Cogito on top
|
||||
of it. Cogito works a bit differently and you usually do not
|
||||
@ -463,10 +465,10 @@ can explore on your own.
|
||||
and runs "git-update-cache" on them for you. ]
|
||||
|
||||
|
||||
Tagging a version
|
||||
-----------------
|
||||
Tagging a version
|
||||
-----------------
|
||||
|
||||
In git, there's two kinds of tags, a "light" one, and a "signed tag".
|
||||
In git, there are two kinds of tags, a "light" one, and an "annotated tag".
|
||||
|
||||
A "light" tag is technically nothing more than a branch, except we put
|
||||
it in the ".git/refs/tags/" subdirectory instead of calling it a "head".
|
||||
@ -485,10 +487,10 @@ obviously be an empty diff, but if you continue to develop and commit
|
||||
stuff, you can use your tag as an "anchor-point" to see what has changed
|
||||
since you tagged it.
|
||||
|
||||
A "signed tag" is actually a real git object, and contains not only a
|
||||
An "annotated tag" is actually a real git object, and contains not only a
|
||||
pointer to the state you want to tag, but also a small tag name and
|
||||
message, along with a PGP signature that says that yes, you really did
|
||||
that tag. You create these signed tags with the "-s" flag to "git tag":
|
||||
message, along with optionally a PGP signature that says that yes, you really did
|
||||
that tag. You create these signed tags with either the "-a" or "-s" flag to "git tag":
|
||||
|
||||
git tag -s <tagname>
|
||||
|
||||
@ -503,10 +505,10 @@ point, just create a private tag for it, and you have a nice symbolic
|
||||
name for the state at that point.
|
||||
|
||||
|
||||
Copying archives
|
||||
-----------------
|
||||
Copying repositories
|
||||
--------------------
|
||||
|
||||
Git archives are normally totally self-sufficient, and it's worth noting
|
||||
Git repositories are normally totally self-sufficient, and it's worth noting
|
||||
that unlike CVS, for example, there is no separate notion of
|
||||
"repository" and "working tree". A git repository normally _is_ the
|
||||
working tree, with the local git information hidden in the ".git"
|
||||
@ -516,40 +518,40 @@ subdirectory. There is nothing else. What you see is what you got.
|
||||
the directory that it tracks, but we'll ignore that for now: it's not
|
||||
how normal projects work, and it's really only meant for special uses.
|
||||
So the mental model of "the git information is always tied directly to
|
||||
the working directory that it describes" may not be technically 100%
|
||||
the working tree that it describes" may not be technically 100%
|
||||
accurate, but it's a good model for all normal use ]
|
||||
|
||||
This has two implications:
|
||||
|
||||
- if you grow bored with the tutorial archive you created (or you've
|
||||
- if you grow bored with the tutorial repository you created (or you've
|
||||
made a mistake and want to start all over), you can just do simple
|
||||
|
||||
rm -rf git-tutorial
|
||||
|
||||
and it will be gone. There's no external repository, and there's no
|
||||
history outside of the project you created.
|
||||
history outside the project you created.
|
||||
|
||||
- if you want to move or duplicate a git archive, you can do so. There
|
||||
- if you want to move or duplicate a git repository, you can do so. There
|
||||
is "git clone" command, but if all you want to do is just to
|
||||
create a copy of your archive (with all the full history that
|
||||
create a copy of your repository (with all the full history that
|
||||
went along with it), you can do so with a regular
|
||||
"cp -a git-tutorial new-git-tutorial".
|
||||
|
||||
Note that when you've moved or copied a git archive, your git index
|
||||
Note that when you've moved or copied a git repository, your git index
|
||||
file (which caches various information, notably some of the "stat"
|
||||
information for the files involved) will likely need to be refreshed.
|
||||
So after you do a "cp -a" to create a new copy, you'll want to do
|
||||
|
||||
git-update-cache --refresh
|
||||
|
||||
to make sure that the index file is up-to-date in the new one.
|
||||
in the new repository to make sure that the index file is up-to-date.
|
||||
|
||||
Note that the second point is true even across machines. You can
|
||||
duplicate a remote git archive with _any_ regular copy mechanism, be it
|
||||
duplicate a remote git repository with _any_ regular copy mechanism, be it
|
||||
"scp", "rsync" or "wget".
|
||||
|
||||
When copying a remote repository, you'll want to at a minimum update the
|
||||
index cache when you do this, and especially with other peoples
|
||||
index cache when you do this, and especially with other peoples'
|
||||
repositories you often want to make sure that the index cache is in some
|
||||
known state (you don't know _what_ they've done and not yet checked in),
|
||||
so usually you'll precede the "git-update-cache" with a
|
||||
@ -557,9 +559,12 @@ so usually you'll precede the "git-update-cache" with a
|
||||
git-read-tree --reset HEAD
|
||||
git-update-cache --refresh
|
||||
|
||||
which will force a total index re-build from the tree pointed to by HEAD
|
||||
(it resets the index contents to HEAD, and then the git-update-cache
|
||||
makes sure to match up all index entries with the checked-out files).
|
||||
which will force a total index re-build from the tree pointed to by HEAD.
|
||||
It resets the index contents to HEAD, and then the git-update-cache
|
||||
makes sure to match up all index entries with the checked-out files.
|
||||
If the original repository had uncommitted changes in its
|
||||
working tree, "git-update-cache --refresh" notices them and
|
||||
tells you they need to be updated.
|
||||
|
||||
The above can also be written as simply
|
||||
|
||||
@ -572,7 +577,7 @@ implemented in "git-reset-script", but some things like "git status" and
|
||||
"git commit" are slightly more complex scripts around the basic git
|
||||
commands).
|
||||
|
||||
NOTE! Many (most?) public remote repositories will not contain any of
|
||||
Many (most?) public remote repositories will not contain any of
|
||||
the checked out files or even an index file, and will _only_ contain the
|
||||
actual core git files. Such a repository usually doesn't even have the
|
||||
".git" subdirectory, but has all the git files directly in the
|
||||
@ -593,7 +598,7 @@ followed by
|
||||
|
||||
to populate the index. However, now you have populated the index, and
|
||||
you have all the git internal files, but you will notice that you don't
|
||||
actually have any of the _working_directory_ files to work on. To get
|
||||
actually have any of the working tree files to work on. To get
|
||||
those, you'd check them out with
|
||||
|
||||
git-checkout-cache -u -a
|
||||
@ -617,11 +622,11 @@ You have now successfully copied somebody else's (mine) remote
|
||||
repository, and checked it out.
|
||||
|
||||
|
||||
Creating a new branch
|
||||
---------------------
|
||||
Creating a new branch
|
||||
---------------------
|
||||
|
||||
Branches in git are really nothing more than pointers into the git
|
||||
object space from within the ".git/refs/" subdirectory, and as we
|
||||
object database from within the ".git/refs/" subdirectory, and as we
|
||||
already discussed, the HEAD branch is nothing but a symlink to one of
|
||||
these object pointers.
|
||||
|
||||
@ -632,7 +637,7 @@ want (and indeed, subdirectories), but the convention is that the
|
||||
"normal" branch is called "master". That's just a convention, though,
|
||||
and nothing enforces it.
|
||||
|
||||
To show that as an example, let's go back to the git-tutorial archive we
|
||||
To show that as an example, let's go back to the git-tutorial repository we
|
||||
used earlier, and create a branch in it. You do that by simply just
|
||||
saying that you want to check out a new branch:
|
||||
|
||||
@ -646,9 +651,9 @@ to it.
|
||||
just telling "git checkout" what the base of the checkout would be.
|
||||
In other words, if you have an earlier tag or branch, you'd just do
|
||||
|
||||
git checkout -b mybranch earlier-branch
|
||||
git checkout -b mybranch earlier-commit
|
||||
|
||||
and it would create the new branch "mybranch" at the earlier point,
|
||||
and it would create the new branch "mybranch" at the earlier commit,
|
||||
and check out the state at that time. ]
|
||||
|
||||
You can always just jump back to your original "master" branch by doing
|
||||
@ -660,9 +665,14 @@ branch you happen to be on, a simple
|
||||
|
||||
ls -l .git/HEAD
|
||||
|
||||
will tell you where it's pointing.
|
||||
will tell you where it's pointing. To get the list of branches
|
||||
you have, you can say
|
||||
|
||||
NOTE! Sometimes you may wish to create a new branch _without_ actually
|
||||
git branch
|
||||
|
||||
which is nothing more than a simple script around "ls .git/refs/heads".
|
||||
|
||||
Sometimes you may wish to create a new branch _without_ actually
|
||||
checking it out and switching to it. If so, just use the command
|
||||
|
||||
git branch <branchname> [startingpoint]
|
||||
@ -673,8 +683,8 @@ on that branch - switch to that branch with a regular "git checkout"
|
||||
with the branchname as the argument.
|
||||
|
||||
|
||||
Merging two branches
|
||||
--------------------
|
||||
Merging two branches
|
||||
--------------------
|
||||
|
||||
One of the ideas of having a branch is that you do some (possibly
|
||||
experimental) work in it, and eventually merge it back to the main
|
||||
@ -684,11 +694,12 @@ that branch, and do some work there.
|
||||
|
||||
git checkout mybranch
|
||||
echo "Work, work, work" >>hello
|
||||
git commit hello
|
||||
git commit -m 'Some work.' hello
|
||||
|
||||
Here, we just added another line to "hello", and we used a shorthand for
|
||||
both going a "git-update-cache hello" and "git commit" by just giving the
|
||||
filename directly to "git commit".
|
||||
filename directly to "git commit". The '-m' flag is to give the
|
||||
commit log message from the command line.
|
||||
|
||||
Now, to make it a bit more interesting, let's assume that somebody else
|
||||
does some work in the original branch, and simulate that by going back
|
||||
@ -702,7 +713,7 @@ hasn't happened in the "master" branch at all. Then do
|
||||
|
||||
echo "Play, play, play" >>hello
|
||||
echo "Lots of fun" >>example
|
||||
git commit hello example
|
||||
git commit -m 'Some fun.' hello example
|
||||
|
||||
since the master branch is obviously in a much better mood.
|
||||
|
||||
@ -730,7 +741,7 @@ the merge can be resolved automatically.
|
||||
|
||||
Now, in this case we've intentionally created a situation where the
|
||||
merge will need to be fixed up by hand, though, so git will do as much
|
||||
of it as it can automatically (which in this case is just merge the "b"
|
||||
of it as it can automatically (which in this case is just merge the "example"
|
||||
file, which had no differences in the "mybranch" branch), and say:
|
||||
|
||||
Simple merge failed, trying Automatic merge
|
||||
@ -769,9 +780,68 @@ switch to it, and continue to work with it if you want to. The
|
||||
from the "master" branch, git will know how you merged it, so you'll not
|
||||
have to do _that_ merge again.
|
||||
|
||||
Another useful tool, especially if you do not work in X-Window
|
||||
environment all the time, is "git show-branch".
|
||||
|
||||
Merging external work
|
||||
---------------------
|
||||
------------------------------------------------
|
||||
$ git show-branch master mybranch
|
||||
* [master] Merged "mybranch" changes.
|
||||
! [mybranch] Some work.
|
||||
--
|
||||
+ [master] Merged "mybranch" changes.
|
||||
+ [master~1] Some fun.
|
||||
++ [mybranch] Some work.
|
||||
------------------------------------------------
|
||||
|
||||
The first two lines indicate that it is showing the two branches
|
||||
and the first line of the commit log message from their
|
||||
top-of-the-tree commits, you are currently on "master" branch
|
||||
(notice the asterisk "*" character), and the first column for
|
||||
the later output lines is used to show commits contained in the
|
||||
"master" branch, and the second column for the "mybranch"
|
||||
branch. Three commits are shown along with their log messages.
|
||||
All of them have plus '+' characters in the first column, which
|
||||
means they are now part of the "master" branch. Only the "Some
|
||||
work" commit has the plus '+' character in the second column,
|
||||
because "mybranch" has not been merged to incorporate these
|
||||
commits from the master branch.
|
||||
|
||||
Now, let's pretend you are the one who did all the work in
|
||||
mybranch, and the fruit of your hard work has finally been merged
|
||||
to the master branch. Let's go back to "mybranch", and run
|
||||
resolve to get the "upstream changes" back to your branch.
|
||||
|
||||
git checkout mybranch
|
||||
git resolve HEAD master "Merge upstream changes."
|
||||
|
||||
This outputs something like this (the actual commit object names
|
||||
would be different)
|
||||
|
||||
Updating from ae3a2da... to a80b4aa....
|
||||
example | 1 +
|
||||
hello | 1 +
|
||||
2 files changed, 2 insertions(+), 0 deletions(-)
|
||||
|
||||
Because your branch did not contain anything more than what are
|
||||
already merged into the master branch, the resolve operation did
|
||||
not actually do a merge. Instead, it just updated the top of
|
||||
the tree of your branch to that of the "master" branch. This is
|
||||
often called "fast forward" merge.
|
||||
|
||||
You can run "gitk --all" again to see how the commit ancestry
|
||||
looks like, or run "show-branch", which tells you this.
|
||||
|
||||
------------------------------------------------
|
||||
$ git show-branch master mybranch
|
||||
! [master] Merged "mybranch" changes.
|
||||
* [mybranch] Merged "mybranch" changes.
|
||||
--
|
||||
++ [master] Merged "mybranch" changes.
|
||||
------------------------------------------------
|
||||
|
||||
|
||||
Merging external work
|
||||
---------------------
|
||||
|
||||
It's usually much more common that you merge with somebody else than
|
||||
merging with your own branches, so it's worth pointing out that git
|
||||
@ -817,6 +887,9 @@ pull from:
|
||||
course, you will pay the price of more disk usage to hold
|
||||
multiple working trees, but disk space is cheap these days. ]
|
||||
|
||||
[ Digression #2: you could even pull from your own repository by
|
||||
giving '.' as <remote-repository> parameter to "git pull". ]
|
||||
|
||||
It is likely that you will be pulling from the same remote
|
||||
repository from time to time. As a short hand, you can store
|
||||
the remote repository URL in a file under .git/branches/
|
||||
@ -830,8 +903,7 @@ and use the filename to "git pull" instead of the full URL.
|
||||
The contents of a file under .git/branches can even be a prefix
|
||||
of a full URL, like this:
|
||||
|
||||
echo rsync://kernel.org/pub/.../jgarzik/
|
||||
>.git/branches/jgarzik
|
||||
echo rsync://kernel.org/pub/.../jgarzik/ >.git/branches/jgarzik
|
||||
|
||||
Examples.
|
||||
|
||||
@ -846,22 +918,22 @@ the above are equivalent to:
|
||||
(3) git pull rsync://kernel.org/pub/.../jgarzik/netdev-2.6.git e100
|
||||
|
||||
|
||||
Publishing your work
|
||||
--------------------
|
||||
Publishing your work
|
||||
--------------------
|
||||
|
||||
So we can use somebody else's work from a remote repository; but
|
||||
how can _you_ prepare a repository to let other people pull from
|
||||
it?
|
||||
|
||||
Your do your real work in your working directory that has your
|
||||
Your do your real work in your working tree that has your
|
||||
primary repository hanging under it as its ".git" subdirectory.
|
||||
You _could_ make that repository accessible remotely and ask
|
||||
people to pull from it, but in practice that is not the way
|
||||
things are usually done. A recommended way is to have a public
|
||||
repository, make it reachable by other people, and when the
|
||||
changes you made in your primary working directory are in good
|
||||
shape, update the public repository from it. This is often
|
||||
called "pushing".
|
||||
changes you made in your primary working tree are in good shape,
|
||||
update the public repository from it. This is often called
|
||||
"pushing".
|
||||
|
||||
[ Side note: this public repository could further be mirrored,
|
||||
and that is how kernel.org git repositories are done. ]
|
||||
@ -925,28 +997,13 @@ propagation to other publicly visible machines:
|
||||
git push master.kernel.org:/pub/scm/git/git.git/
|
||||
|
||||
|
||||
[ Digression: your GIT "public" repository people can pull from
|
||||
is different from a public CVS repository that lets read-write
|
||||
access to multiple developers. It is a copy of _your_ primary
|
||||
repository published for others to use, and you should not
|
||||
push into it from more than one repository (this means, not
|
||||
just disallowing other developers to push into it, but also
|
||||
you should push into it from a single repository of yours).
|
||||
Sharing the result of work done by multiple people are always
|
||||
done by pulling (i.e. fetching and merging) from public
|
||||
repositories of those people. Typically this is done by the
|
||||
"project lead" person, and the resulting repository is
|
||||
published as the public repository of the "project lead" for
|
||||
everybody to base further changes on. ]
|
||||
|
||||
|
||||
Packing your repository
|
||||
-----------------------
|
||||
Packing your repository
|
||||
-----------------------
|
||||
|
||||
Earlier, we saw that one file under .git/objects/??/ directory
|
||||
is stored for each git object you create. This representation
|
||||
is convenient and efficient to create atomically and safely, but
|
||||
not so to transport over the network. Since git objects are
|
||||
not so convenient to transport over the network. Since git objects are
|
||||
immutable once they are created, there is a way to optimize the
|
||||
storage by "packing them together". The command
|
||||
|
||||
@ -990,7 +1047,7 @@ If you run "git repack" again at this point, it will say
|
||||
"Nothing to pack". Once you continue your development and
|
||||
accumulate the changes, running "git repack" again will create a
|
||||
new pack, that contains objects created since you packed your
|
||||
archive the last time. We recommend that you pack your project
|
||||
repository the last time. We recommend that you pack your project
|
||||
soon after the initial import (unless you are starting your
|
||||
project from scratch), and then run "git repack" every once in a
|
||||
while, depending on how active your project is.
|
||||
@ -1000,8 +1057,8 @@ objects packed in the source repository are usually stored
|
||||
unpacked in the destination, unless rsync transport is used.
|
||||
|
||||
|
||||
Working with Others
|
||||
-------------------
|
||||
Working with Others
|
||||
-------------------
|
||||
|
||||
Although git is a truly distributed system, it is often
|
||||
convenient to organize your project with an informal hierarchy
|
||||
@ -1106,4 +1163,24 @@ like this:
|
||||
step (2) and continue.
|
||||
|
||||
|
||||
Working with Others, Shared Repository Style
|
||||
--------------------------------------------
|
||||
|
||||
If you are coming from CVS background, the style of cooperation
|
||||
suggested in the previous section may be new to you. You do not
|
||||
have to worry. git supports "shared public repository" style of
|
||||
cooperation you are more familiar with as well.
|
||||
|
||||
For this, you should set up a public repository on a machine
|
||||
that are reachable via SSH by people with "commit privileges".
|
||||
Put them in the same user group and make the repository writable
|
||||
by that group. Then, each committer would first merge with the
|
||||
head of the branch of choice, and run "git push" to update the
|
||||
branch at the public repository. "git push" refuses to update
|
||||
if the reference on the remote side is not an ancestor of the
|
||||
commit you are pushing, to prevent you from overwriting changes
|
||||
made by somebody else.
|
||||
|
||||
|
||||
|
||||
[ to be continued.. cvsimports ]
|
||||
|
||||
Loading…
Reference in New Issue
Block a user