references in these `refs` subdirectories when you actually start
populating your tree.
+[NOTE]
+An advanced user may want to take a look at the
+link:repository-layout.html[repository layout] document
+after finishing this tutorial.
+
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.
- commit that index file as an object.
The first step is trivial: when you want to tell git about any changes
-to your working tree, you use the `git-update-cache` program. That
+to your working tree, you use the `git-update-index` 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
So to populate the index with the two files you just created, you can do
------------------------------------------------
-git-update-cache --add hello example
+git-update-index --add hello example
------------------------------------------------
and you have now told git to track those two files.
Anyway, as we mentioned previously, you normally never actually take a
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
+was just to show that `git-update-index` did something magical, and
actually saved away the contents of your files into the git object
database.
Making a change
---------------
-Remember how we did the `git-update-cache` on file `hello` and then we
+Remember how we did the `git-update-index` on file `hello` and then we
changed `hello` afterward, and could compare the new state of `hello` with the
state we saved in the index file?
we'll still see the same difference we saw last time: the index file
hasn't changed by the act of committing anything. However, now that we
have committed something, we can also learn to use a new command:
-`git-diff-cache`.
+`git-diff-index`.
Unlike `git-diff-files`, which showed the difference between the index
-file and the working tree, `git-diff-cache` shows the differences
+file and the working tree, `git-diff-index` shows the differences
between a committed *tree* and either the index file or the working
-tree. In other words, `git-diff-cache` wants a tree to be diffed
+tree. In other words, `git-diff-index` 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
- git-diff-cache -p HEAD
+ git-diff-index -p HEAD
(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.
which ends up doing the above for you.
-In other words, `git-diff-cache` normally compares a tree against the
+In other words, `git-diff-index` normally compares a tree against the
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 tree state entirely. Since we just wrote the index
-file to HEAD, doing `git-diff-cache \--cached -p HEAD` should thus return
+file to HEAD, doing `git-diff-index \--cached -p HEAD` should thus return
an empty set of differences, and that's exactly what it does.
[NOTE]
================
-`git-diff-cache` really always uses the index for its
+`git-diff-index` really always uses the index for its
comparisons, and saying that it compares a tree against the working
tree is thus not strictly accurate. In particular, the list of
files to compare (the "meta-data") *always* comes from the index file,
update the index cache:
------------------------------------------------
-git-update-cache hello
+git-update-index hello
------------------------------------------------
(note how we didn't need the `\--add` flag this time, since git knew
Note what happens to the different `git-diff-\*` versions here. After
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
+differences, but `git-diff-index -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`
+`git-diff-index` shows the same difference whether we use the `--cached`
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
looking at what `git commit` really does, feel free to investigate:
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 (`git-commit-script`).
+commit itself (`git-commit`).
-Checking it out
----------------
+Inspecting Changes
+------------------
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
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
-have to run `git-update-cache` yourself for changed files (you
+have to run `git-update-index` yourself for changed files (you
do tell underlying git about additions and removals via
`cg-add` and `cg-rm` commands). Just before you make a commit
with `cg-commit`, Cogito figures out which files you modified,
-and runs `git-update-cache` on them for you.
+and runs `git-update-index` on them for you.
Tagging a version
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
+ git-update-index --refresh
+
in the new repository to make sure that the index file is up-to-date.
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
+so usually you'll precede the `git-update-index` with a
git-read-tree --reset HEAD
- git-update-cache --refresh
+ git-update-index --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`
+It resets the index contents to `HEAD`, and then the `git-update-index`
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
+working tree, `git-update-index --refresh` notices them and
tells you they need to be updated.
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).
+with the `git xyz` interfaces. You can learn things by just looking
+at what the various git scripts do. For example, `git reset` is the
+above two lines implemented in `git-reset`, but some things like
+`git status` and `git commit` are slightly more complex scripts around
+the basic git commands.
Many (most?) public remote repositories will not contain any of
the checked out files or even an index file, and will *only* contain the
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
+ git-checkout-index -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` flag 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`
-flag first, to tell git-checkout-cache to *force* overwriting of any old
+flag first, to tell git-checkout-index to *force* overwriting of any old
files).
Again, this can all be simplified with
------------------------------------------------
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
+doing both `git-update-index hello` and `git commit` by just giving the
filename directly to `git commit`. The `-m` flag is to give the
commit log message from the command line.
(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
+After you're done, start up `gitk \--all` to see graphically what the
history looks like. Notice 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
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.
+commits from the master branch. The string inside brackets
+before the commit log message is a short name you can use to
+name the commit. In the above example, 'master' and 'mybranch'
+are branch heads. 'master~1' is the first parent of 'master'
+branch head. Please see 'git-rev-parse' documentation if you
+see more complex cases.
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
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
+You can run `gitk \--all` again to see how the commit ancestry
looks like, or run `show-branch`, which tells you this.
------------------------------------------------
server like GIT Native transport does. Any stock HTTP server
would suffice.
+
-There are (confusingly enough) `git-ssh-pull` and `git-ssh-push`
+There are (confusingly enough) `git-ssh-fetch` and `git-ssh-upload`
programs, which are 'commit walkers'; they outlived their
usefulness when GIT Native and SSH transports were introduced,
and not used by `git pull` or `git push` scripts.
`.bash_profile`. As a workaround, make sure `.bashrc` sets up
`$PATH` so that you can run `git-receive-pack` program.
+[NOTE]
+If you plan to publish this repository to be accessed over http,
+you should do `chmod +x my-git.git/hooks/post-update` at this
+point. This makes sure that every time you push into this
+repository, `git-update-server-info` is run.
+
Your "public repository" is now ready to accept your changes.
Come back to the machine you have your private repository. From
there, run this command:
back before you push your work when it happens.
+Bundling your work together
+---------------------------
+
+It is likely that you will be working on more than one thing at
+a time. It is easy to use those more-or-less independent tasks
+using branches with git.
+
+We have already seen how branches work in a previous example,
+with "fun and work" example using two branches. The idea is the
+same if there are more than two branches. Let's say you started
+out from "master" head, and have some new code in the "master"
+branch, and two independent fixes in the "commit-fix" and
+"diff-fix" branches:
+
+------------
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+ * [master] Release candidate #1
+---
+ + [diff-fix] Fix rename detection.
+ + [diff-fix~1] Better common substring algorithm.
++ [commit-fix] Fix commit message normalization.
+ + [master] Release candidate #1
++++ [diff-fix~2] Pretty-print messages.
+------------
+
+Both fixes are tested well, and at this point, you want to merge
+in both of them. You could merge in 'diff-fix' first and then
+'commit-fix' next, like this:
+
+------------
+$ git resolve master diff-fix 'Merge fix in diff-fix'
+$ git resolve master commit-fix 'Merge fix in commit-fix'
+------------
+
+Which would result in:
+
+------------
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+ * [master] Merge fix in commit-fix
+---
+ + [master] Merge fix in commit-fix
++ + [commit-fix] Fix commit message normalization.
+ + [master~1] Merge fix in diff-fix
+ ++ [diff-fix] Fix rename detection.
+ ++ [diff-fix~1] Better common substring algorithm.
+ + [master~2] Release candidate #1
++++ [master~3] Pretty-print messages.
+------------
+
+However, there is no particular reason to merge in one branch
+first and the other next, when what you have are a set of truly
+independent changes (if the order mattered, then they are not
+independent by definition). You could instead merge those two
+branches into the current branch at once. First let's undo what
+we just did and start over. We would want to get the master
+branch before these two merges by resetting it to 'master~2':
+
+------------
+$ git reset --hard master~2
+------------
+
+You can make sure 'git show-branch' matches the state before
+those two 'git resolve' you just did. Then, instead of running
+two 'git resolve' commands in a row, you would pull these two
+branch heads (this is known as 'making an Octopus'):
+
+------------
+$ git pull . commit-fix diff-fix
+$ git show-branch
+! [commit-fix] Fix commit message normalization.
+ ! [diff-fix] Fix rename detection.
+ * [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
+---
+ + [master] Octopus merge of branches 'diff-fix' and 'commit-fix'
++ + [commit-fix] Fix commit message normalization.
+ ++ [diff-fix] Fix rename detection.
+ ++ [diff-fix~1] Better common substring algorithm.
+ + [master~1] Release candidate #1
++++ [master~2] Pretty-print messages.
+------------
+
+Note that you should not do Octopus because you can. An octopus
+is a valid thing to do and often makes it easier to view the
+commit history if you are pulling more than two independent
+changes at the same time. However, if you have merge conflicts
+with any of the branches you are merging in and need to hand
+resolve, that is an indication that the development happened in
+those branches were not independent after all, and you should
+merge two at a time, documenting how you resolved the conflicts,
+and the reason why you preferred changes made in one side over
+the other. Otherwise it would make the project history harder
+to follow, not easier.
+
[ to be continued.. cvsimports ]