read-tree: document --exclude-per-directory
[gitweb.git] / Documentation / core-tutorial.txt
index 35579cc5b0ccaf4eeac8cf134d887ccb5182550b..47505aa20a56b4dc29fad86d66e8c6638edf03e0 100644 (file)
@@ -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 <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
+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
@@ -813,18 +813,12 @@ $ git checkout master
 (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
@@ -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
@@ -1623,123 +1620,7 @@ 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 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
 ---------------------------