doing.
The core git is often called "plumbing", with the prettier user
-interfaces on top of it called "porcelain". You may want to know what
-the plumbing does for when the porcelain isn't flushing...
+interfaces on top of it called "porcelain". You may not want to use the
+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
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 arhive from
+For our first example, we're going to start a totally new archive 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":
defaulting to local storage area
-which is just gits way of saying that you haven't been doing anything
+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
- a symlink called HEAD, pointing to "refs/heads/master"
Don't worry about the fact that the file that the HEAD link points to
- dosn't even exist yet - you haven't created the commit that will
+ 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
One note: the special "master" head is the default branch, which is
why the .git/HEAD file was created as a symlink to it even if it
- doesn't yet exist. Bascially, the HEAD link is supposed to always
+ doesn't yet exist. Basically, the HEAD link is supposed to always
point to the branch you are working on right now, and you always
start out expecting to work on the "master" branch.
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 ne wobjects to the object
+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
ls .git/objects/??/*
more than the contents of your file "a".
[ Digression: don't confuse that object with the file "a" itself. The
-object is literally just those specific _contents_ of the file, and
-however much you later change the contents in file "a", the object we
-just looked at will never change. Objects are immutable. ]
+ object is literally just those specific _contents_ of the file, and
+ however much you later change the contents in file "a", the object we
+ just looked at will never change. Objects are immutable. ]
Anyway, as we mentioned previously, you normally never actually take a
look at the objects themselves, and typing long 40-character hex SHA1
you have not actually really "checked in" your files into git so far,
you've only _told_ git about them.
-However, since git knows about them, you can how start using some of the
+However, since git knows about them, you can now start using some of the
most basic git commands to manipulate the files or look at their status.
In particular, let's not even check in the two files into git yet, we'll
what is recorded in the index, and what is currently in the working
tree. That's very useful.
+A common shorthand for "git-diff-files -p" is to just write
+
+ git diff
+
+which will do the same thing.
+
Committing git state
--------------------
earlier commit, and you'll never see this "Committing initial tree"
message ever again.
+Again, normally you'd never actually do this by hand. There is a
+helpful script called "git commit" that will do all of this for you. So
+you could have just writtten
+
+ git commit
+
+instead, and it would have done the above magic scripting for you.
+
Making a change
---------------
Remember how we did the "git-update-cache" on file "a" and then we
-changed "a" afterwards, and could compare the new state of "a" with the
+changed "a" afterward, and could compare the new state of "a" with the
state we saved in the index file?
Further, remember how I said that "git-write-tree" writes the contents
Unlike "git-diff-files", which showed the difference between the index
file and the working directory, "git-diff-cache" shows the differences
-between a committed _tree_ and the index file. 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.
+between a committed _tree_ and either the the index file or the working
+directory. 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.
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 not comparing against the index file, we're comparing against
-the tree we just wrote. It just so happens that those two are obviously
-the same.
-
-"git-diff-cache" also has a specific flag "--cached", which is used to
-tell it to show the differences purely with the index file, and ignore
-the current working directory 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.
+Now we're comparing the working directory 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.
+
+Again, because this is a common operation, you can also just shorthand
+it with
+
+ git diff HEAD
+
+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
+instead compare against just the index cache contents, and ignore the
+current working directory 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
+ 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.
+
+ 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
+ explicitly. Git will never go _looking_ for files to compare, it
+ expects you to tell it what the files are, and that's what the index
+ is there for. ]
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 "workign
+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
work through the index file, so the first thing we need to do is to
flag or not, since now the index is coherent with the working directory.
Now, since we've updated "a" in the index, we can commit the new
-version. We could do it by writing the tree by hand, and committing the
-tree (this time we'd have to use the "-p HEAD" flag to tell commit that
-the HEAD was the _parent_ fo the new commit, and that this wasn't an
-initial commit any more), but the fact is, git has a simple helper
-script for doing all of the non-initial commits that does all of this
-for you, and starts up an editor to let you write your commit message
-yourself, so let's just use that:
+version. We could do it by writing the tree by hand again, and
+committing the tree (this time we'd have to use the "-p HEAD" flag to
+tell commit that the HEAD was the _parent_ of the new commit, and that
+this wasn't an initial commit any more), but you've done that once
+already, so let's just use the helpful script this time:
- git-commit-script
+ git commit
+
+which starts an editor for you to write the commit message and tells you
+a bit about what you're doing.
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
can just leave an empty message. Otherwise git-commit-script will commit
the change for you.
-(Btw, current versions of git will consider the change in question to be
-so big that it's considered a whole new file, since the diff is actually
-bigger than the file. So the helpful comments that git-commit-script
-tells you for this example will say that you deleted and re-created the
-file "a". For a less contrieved example, these things are usually more
-obvious).
-
You've now made your first real git commit. And if you're interested in
looking at what git-commit-script really does, feel free to investigate:
it's a few very simple shell scripts to generate the helpful (?) commit
included with git which does exactly this, and shows a log of recent
activity.
-To see the whole history of our pitiful little git-tutorial project, we
+To see the whole history of our pitiful little git-tutorial project, you
can do
- git-whatchanged -p --root HEAD
+ git log
+
+which shows just the log messages, or if we want to see the log together
+with the associated patches use the more complex (and much more
+powerful)
-(the "--root" flag is a flag to git-diff-tree to tell it to show the
-initial aka "root" commit as a diff too), and you will see exactly what
-has changed in the repository over its short history.
+ git-whatchanged -p --root
-With that, you should now be having some incling of what git does, and
+and you will see exactly what has changed in the repository over its
+short history.
+
+[ Side note: the "--root" flag is a flag to git-diff-tree to tell it to
+ 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 ]
+
+With that, you should now be having some inkling of what git does, and
can explore on your own.
-[ to be continued.. cvs2git, tagging versions, branches, merging.. ]
+
+ Copying archives
+ -----------------
+
+Git archives 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"
+subdirectory. There is nothing else. What you see is what you got.
+
+[ Side note: you can tell git to split the git internal information from
+ 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%
+ 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
+ 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.
+
+ - if you want to move or duplicate a git archive, you can do so. There
+ is no "git clone" command: if you want to create a copy of your
+ archive (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
+ 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.
+
+Note that the second point is true even across machines. You can
+duplicate a remote git archive 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
+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
+
+ 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).
+
+The above can also be written as simply
+
+ git reset
+
+and in fact a lot of the common git command combinations can be scripted
+with the "git xyz" interfaces, and you can learn things by just looking
+at what the git-*-script scripts do ("git reset" is the above two lines
+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
+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
+repository.
+
+To create your own local live copy of such a "raw" git repository, you'd
+first create your own subdirectory for the project, and then copy the
+raw repository contents into the ".git" directory. For example, to
+create your own copy of the git repository, you'd do the following
+
+ mkdir my-git
+ cd my-git
+ rsync -rL rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/git.git/ .git
+
+followed by
+
+ git-read-tree HEAD
+
+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
+those, you'd check them out with
+
+ git-checkout-cache -u -a
+
+where the "-u" flag means that you want the checkout to keep the index
+up-to-date (so that you don't have to refresh it afterward), and the
+"-a" file means "check out all files" (if you have a stale copy or an
+older version of a checked out tree you may also need to add the "-f"
+file first, to tell git-checkout-cache to _force_ overwriting of any old
+files).
+
+Again, this can all be simplified with
+
+ git clone rsync://rsync.kernel.org/pub/scm/linux/kernel/git/torvalds/git.git/ my-git
+ cd my-git
+ git checkout
+
+which will end up doing all of the above for you.
+
+You have now successfully copied somebody else's (mine) remote
+repository, and checked it out.
+
+
+ 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
+already discussed, the HEAD branch is nothing but a symlink to one of
+these object pointers.
+
+You can at any time create a new branch by just picking an arbitrary
+point in the project history, and just writing the SHA1 name of that
+object into a file under .git/refs/heads/. You can use any filename you
+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
+used earlier, and create a branch in it. You literally do that by just
+creating a new SHA1 reference file, and switch to it by just making the
+HEAD pointer point to it:
+
+ cat .git/HEAD > .git/refs/heads/mybranch
+ ln -sf refs/heads/mybranch .git/HEAD
+
+and you're done.
+
+Now, if you make the decision to start your new branch at some other
+point in the history than the current HEAD, you usually also want to
+actually switch the contents of your working directory to that point
+when you switch the head, and "git checkout" will do that for you:
+instead of switching the branch by hand with "ln -sf", you can just do
+
+ git checkout mybranch
+
+which will basically "jump" to the branch specified, update your working
+directory to that state, and also make it become the new default HEAD.
+
+You can always just jump back to your original "master" branch by doing
+
+ git checkout master
+
+and if you forget which branch you happen to be on, a simple
+
+ ls -l .git/HEAD
+
+will tell you where it's pointing.
+
+
+ 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
+branch. So assuming you created the above "mybranch" that started out
+being the same as the original "master" branch, let's make sure we're in
+that branch, and do some work there.
+
+ git checkout mybranch
+ echo "Work, work, work" >> a
+ git commit a
+
+Here, we just added another line to "a", and we used a shorthand for
+both going a "git-update-cache a" and "git commit" by just giving the
+filename directly to "git commit".
+
+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
+to the master branch, and editing the same file differently there:
+
+ git checkout master
+
+Here, take a moment to look at the contents of "a", and notice how they
+don't contain the work we just did in "mybranch" - because that work
+hasn't happened in the "master" branch at all. Then do
+
+ echo "Play, play, play" >> a
+ echo "Lots of fun" >> b
+ git commit a b
+
+since the master branch is obviously in a much better mood.
+
+Now, you've got two branches, and you decide that you want to merge the
+work done. Before we do that, let's introduce a cool graphical tool that
+helps you view what's going on:
+
+ gitk --all
+
+will show you graphically both of your branches (that's what the "--all"
+means: normally it will just show you your current HEAD) and their
+histories. You can also see exactly how they came to be from a common
+source.
+
+Anyway, let's exit gitk (^Q or the File menu), and decide that we want
+to merge the work we did on the "mybranch" branch into the "master"
+branch (which is currently our HEAD too). To do that, there's a nice
+script called "git resolve", which wants to know which branches you want
+to resolve and what the merge is all about:
+
+ git resolve HEAD mybranch "Merge work in mybranch"
+
+where the third argument is going to be used as the commit message if
+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"
+file, which had no differences in the "mybranch" branch), and say:
+
+ Simple merge failed, trying Automatic merge
+ Auto-merging a.
+ merge: warning: conflicts during merge
+ ERROR: Merge conflict in a.
+ fatal: merge program failed
+ Automatic merge failed, fix up by hand
+
+which is way too verbose, but it basically tells you that it failed the
+really trivial merge ("Simple merge") and did an "Automatic merge"
+instead, but that too failed due to conflicts in "a".
+
+Not to worry. It left the (trivial) conflict in "a" in the same form you
+should already be well used to if you've ever used CVS, so let's just
+open "a" in our editor (whatever that may be), and fix it up somehow.
+I'd suggest just making it so that "a" contains all four lines:
+
+ Hello World
+ It's a new day for git
+ Play, play, play
+ Work, work, work
+
+and once you're happy with your manual merge, just do a
+
+ git commit a
+
+which will very loudly warn you that you're now committing a merge
+(which is correct, so never mind), and you can write a small merge
+message about your adventures in git-merge-land.
+
+After you're done, start up "gitk --all" to see graphically what the
+history looks like. Notive that "mybranch" still exists, and you can
+switch to it, and continue to work with it if you want to. The
+"mybranch" branch will not contain the merge, but next time you merge it
+from the "master" branch, git will know how you merged it, so you'll not
+have to do _that_ merge again.
+
+
+ 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
+makes that very easy too, and in fact, it's not that different from
+doing a "git resolve". In fact, a remote merge ends up being nothing
+more than "fetch the work from a remote repository into a temporary tag"
+followed by a "git resolve".
+
+It's such a common thing to do that it's called "git pull", and you can
+simply do
+
+ git pull <remote-repository>
+
+and optionally give a branch-name for the remote end as a second
+argument.
+
+[ Todo: fill in real examples ]
+
+
+ Tagging a version
+ -----------------
+
+In git, there's two kinds of tags, a "light" one, and a "signed 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".
+So the simplest form of tag involves nothing more than
+
+ cat .git/HEAD > .git/refs/tags/my-first-tag
+
+after which point you can use this symbolic name for that particular
+state. You can, for example, do
+
+ git diff my-first-tag
+
+to diff your current state against that tag (which at this point will
+obviously be an empty diff, but if you continue to develop and commit
+stuff, you can use your tag as a "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
+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
+
+ git tag <tagname>
+
+which will sign the current HEAD (but you can also give it another
+argument that specifies the thing to tag, ie you could have tagged the
+current "mybranch" point by using "git tag <tagname> mybranch").
+
+You normally only do signed tags for major releases or things
+like that, while the light-weight tags are useful for any marking you
+want to do - any time you decide that you want to remember a certain
+point, just create a private tag for it, and you have a nice symbolic
+name for the state at that point.
+
+[ to be continued.. cvsimports, pushing and pulling ]
projects / git.git / blobdiff