X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=Documentation%2Fcore-tutorial.txt;h=1185897f7078a83bebce0366192038f72bbc1d84;hb=HEAD;hp=4513ad635f2cbea21e4d624ec2578a3d59148759;hpb=b8bc67cef31453233f1ff6722c0bd3c99df44756;p=git.git diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 4513ad63..1185897f 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -1,5 +1,5 @@ -A short git tutorial -==================== +A git core tutorial for developers +================================== Introduction ------------ @@ -66,9 +66,9 @@ your new project. You will now have a `.git` directory, and you can 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 @@ -89,7 +89,7 @@ of different 'heads' of development (aka 'branches'), and to any 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. @@ -133,8 +133,8 @@ $ echo "Hello World" >hello $ 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. @@ -173,8 +173,8 @@ and see two files: .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: @@ -184,14 +184,14 @@ $ git-cat-file -t 557db03de997c86a4a028e1ebd3a1ceb225be238 ---------------- 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] @@ -530,8 +530,8 @@ various diff-\* commands compare things. +-----------+ ============ -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. @@ -619,7 +619,7 @@ $ git tag -s ---------------- 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 mybranch`). You normally only do signed tags for major releases or things @@ -814,17 +814,11 @@ $ git checkout master 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 @@ -858,12 +852,14 @@ that branch, and do some work there. ------------------------------------------------ $ 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 @@ -881,7 +877,7 @@ hasn't happened in the `master` branch at all. Then do ------------ $ 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. @@ -924,7 +920,7 @@ file, which had no differences in the `mybranch` branch), and say: ... 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 @@ -946,7 +942,7 @@ Work, work, work 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 @@ -964,7 +960,7 @@ Another useful tool, especially if you do not always work in X-Window 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. -- @@ -975,7 +971,7 @@ $ git show-branch master mybranch 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. @@ -1006,6 +1002,7 @@ would be different) ---------------- Updating from ae3a2da... to a80b4aa.... +Fast forward example | 1 + hello | 1 + 2 files changed, 2 insertions(+), 0 deletions(-) @@ -1100,7 +1097,7 @@ commit object by downloading from `repo.git/objects/xx/xxx\...` 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