-A short git tutorial
-====================
+A git core tutorial for developers
+==================================
Introduction
------------
inspect that with `ls`. For your new empty project, it should show you
three entries, among other things:
- - a symlink called `HEAD`, pointing to `refs/heads/master` (if your
- platform does not have native symlinks, it is a file containing the
- line "ref: refs/heads/master")
+ - a file called `HEAD`, that has `ref: refs/heads/master` in it.
+ This is similar to a symbolic link and points at
+ `refs/heads/master` relative to the `HEAD` file.
+
Don't worry about the fact that the file that the `HEAD` link points to
doesn't even exist yet -- you haven't created the commit that will
repository.
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
+why the `.git/HEAD` file was created points to it even if it
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.
$ echo "Silly example" >example
------------------------------------------------
-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:
+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 'index' file (aka 'cache') with the information about your
working tree state.
.git/objects/f2/4c74a2e500f5ee1332c86b94199f52b1d1d962
----------------
-which correspond with the objects with names of 557db... and f24c7..
-respectively.
+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
you'll have to use the object name, not the filename of the object:
----------------
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
+object is. git will tell you that you have a "blob" object (i.e., just a
regular file), and you can see the contents with
----------------
$ git-cat-file "blob" 557db03
----------------
-which will print out "Hello World". The object 557db03 is nothing
+which will print out "Hello World". The object `557db03` is nothing
more than the contents of your file `hello`.
[NOTE]
+-----------+
============
-More interestingly, you can also give `git-diff-tree` the `-v` flag, which
-tells it to also show the commit message and author and date of the
+More interestingly, you can also give `git-diff-tree` the `--pretty` flag,
+which tells it to also show the commit message and author and date of the
commit, and you can tell it to show a whole series of diffs.
Alternatively, you can tell it to be "silent", and not show the diffs at
all, but just show the actual commit message.
----------------
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
+argument that specifies the thing to tag, i.e., 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
(or any other branch-name, for that matter) and if you forget which
branch you happen to be on, a simple
-------------
-$ ls -l .git/HEAD
-------------
-
-will tell you where it's pointing (Note that on platforms with bad or no
-symlink support, you have to execute
-
------------
$ cat .git/HEAD
------------
-instead). To get the list of branches you have, you can say
+will tell you where it's pointing. To get the list of branches
+you have, you can say
------------
$ git branch
------------------------------------------------
$ git checkout mybranch
$ echo "Work, work, work" >>hello
-$ git commit -m 'Some work.' hello
+$ git commit -m 'Some work.' -i hello
------------------------------------------------
Here, we just added another line to `hello`, and we used a shorthand for
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
+filename directly to `git commit`, with an `-i` flag (it tells
+git to 'include' that file in addition to what you have done to
+the index file so far when making the 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
------------
$ echo "Play, play, play" >>hello
$ echo "Lots of fun" >>example
-$ git commit -m 'Some fun.' hello example
+$ git commit -m 'Some fun.' -i hello example
------------
since the master branch is obviously in a much better mood.
...
Auto-merging hello
CONFLICT (content): Merge conflict in hello
- Automatic merge failed/prevented; fix up by hand
+ Automatic merge failed; fix up by hand
----------------
which is way too verbose, but it basically tells you that it failed the
and once you're happy with your manual merge, just do a
------------
-$ git commit hello
+$ git commit -i hello
------------
which will very loudly warn you that you're now committing a merge
environment, is `git show-branch`.
------------------------------------------------
-$ git show-branch master mybranch
+$ git show-branch --topo-order master mybranch
* [master] Merge work in mybranch
! [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
+(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.
----------------
Updating from ae3a2da... to a80b4aa....
+Fast forward
example | 1 +
hello | 1 +
2 files changed, 2 insertions(+), 0 deletions(-)
using the object name of that commit object. Then it reads the
commit object to find out its parent commits and the associate
tree object; it repeats this process until it gets all the
-necessary objects. Because of this behaviour, they are
+necessary objects. Because of this behavior, they are
sometimes also called 'commit walkers'.
+
The 'commit walkers' are sometimes also called 'dumb
have to worry. git supports "shared public repository" style of
cooperation you are probably more familiar with as well.
-For this, set up a public repository on a machine that is
-reachable via SSH by people with "commit privileges". Put the
-committers in the same user group and make the repository
-writable by that group. Make sure their umasks are set up to
-allow group members to write into directories other members
-have created.
-
-You, as an individual committer, then:
-
-- First clone the shared repository to a local repository:
-------------------------------------------------
-$ git clone repo.shared.xz:/pub/scm/project.git/ my-project
-$ cd my-project
-$ hack away
-------------------------------------------------
-
-- Merge the work others might have done while you were hacking
- away:
-------------------------------------------------
-$ git pull origin
-$ test the merge result
-------------------------------------------------
-[NOTE]
-================================
-The first `git clone` would have placed the following in
-`my-project/.git/remotes/origin` file, and that's why this and
-the next step work.
-------------
-URL: repo.shared.xz:/pub/scm/project.git/ my-project
-Pull: master:origin
-------------
-================================
-
-- push your work as the new head of the shared
- repository.
-------------------------------------------------
-$ git push origin master
-------------------------------------------------
-If somebody else pushed into the same shared repository while
-you were working locally, `git push` in the last step would
-complain, telling you that the remote `master` head does not
-fast forward. You need to pull and merge those other changes
-back before you push your work when it happens.
-
-The `git push` command without any explicit refspec parameter
-pushes the refs that exist both in the local repository and the
-remote repository. So the last `push` can be done with either
-one of these:
-------------
-$ git push origin
-$ git push repo.shared.xz:/pub/scm/project.git/
-------------
-as long as the shared repository does not have any branches
-other than `master`.
-[NOTE]
-============
-If you created your shared repository by cloning from somewhere
-else, you may have the `origin` branch. Your developers
-typically do not use that branch; remove it. Otherwise, that
-would be pushed back by the `git push origin` because your
-developers' repository would surely have `origin` branch to keep
-track of the shared repository, and would be counted as "exist
-on both ends".
-============
-
-Advanced Shared Repository Management
--------------------------------------
-
-Being able to push into a shared repository means being able to
-write into it. If your developers are coming over the network,
-this means you, as the repository administrator, need to give
-each of them an SSH access to the shared repository machine.
-
-In some cases, though, you may not want to give a normal shell
-account to them, but want to restrict them to be able to only
-do `git push` into the repository and nothing else.
-
-You can achieve this by setting the login shell of your
-developers on the shared repository host to `git-shell` program.
-
-[NOTE]
-Most likely you would also need to list `git-shell` program in
-`/etc/shells` file.
-
-This restricts the set of commands that can be run from incoming
-SSH connection for these users to only `receive-pack` and
-`upload-pack`, so the only thing they can do are `git fetch` and
-`git push`.
-
-You still need to create UNIX user accounts for each developer,
-and put them in the same group. Make sure that the repository
-shared among these developers is writable by that group.
-
-. Initializing the shared repository with `git-init-db --shared`
-helps somewhat.
-
-. Run the following in the shared repository:
-+
-------------
-$ chgrp -R $group repo.git
-$ find repo.git -type d -print | xargs chmod ug+rwx,g+s
-$ GIT_DIR=repo.git git repo-config core.sharedrepository true
-------------
-
-The above measures make sure that directories lazily created in
-`$GIT_DIR` are writable by group members. You, as the
-repository administrator, are still responsible to make sure
-your developers belong to that shared repository group and set
-their umask to a value no stricter than 027 (i.e. at least allow
-reading and searching by group members).
-
-You can implement finer grained branch policies using update
-hooks. There is a document ("control access to branches") in
-Documentation/howto by Carl Baldwin and JC outlining how to (1)
-limit access to branch per user, (2) forbid overwriting existing
-tags.
-
+See link:cvs-migration.html[git for CVS users] for the details.
Bundling your work together
---------------------------