Documentation/user-manual.txt: fix a few omissions of gitlink commands.

[git.git] / Documentation / user-manual.txt

diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index 780f0f0ee64f8ea20e0a4eafe2db039194819fed..2e8c050bb126f8efaf292c111a233dd75a5ef814 100644 (file)
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -42,10 +42,9 @@ How to get a git repository
 It will be useful to have a git repository to experiment with as you
 read this manual.
 
 It will be useful to have a git repository to experiment with as you
 read this manual.
 

-The best way to get one is by using the gitlink:git-clone[1] command
-to download a copy of an existing repository for a project that you
-are interested in.  If you don't already have a project in mind, here
-are some interesting examples:
+The best way to get one is by using the gitlink:git-clone[1] command to
+download a copy of an existing repository.  If you don't already have a
+project in mind, here are some interesting examples:

 
 ------------------------------------------------
        # git itself (approx. 10MB download):
 
 ------------------------------------------------
        # git itself (approx. 10MB download):


@@ -63,21 +62,18 @@ directory, you will see that it contains a copy of the project files,
 together with a special top-level directory named ".git", which
 contains all the information about the history of the project.
 
 together with a special top-level directory named ".git", which
 contains all the information about the history of the project.
 

-In most of the following, examples will be taken from one of the two
-repositories above.
-

 [[how-to-check-out]]
 How to check out a different version of a project
 -------------------------------------------------
 
 [[how-to-check-out]]
 How to check out a different version of a project
 -------------------------------------------------
 

-Git is best thought of as a tool for storing the history of a
-collection of files.  It stores the history as a compressed
-collection of interrelated snapshots (versions) of the project's
-contents.
+Git is best thought of as a tool for storing the history of a collection
+of files.  It stores the history as a compressed collection of
+interrelated snapshots of the project's contents.  In git each such
+version is called a <<def_commit,commit>>.

 
 A single git repository may contain multiple branches.  It keeps track
 of them by keeping a list of <<def_head,heads>> which reference the
 
 A single git repository may contain multiple branches.  It keeps track
 of them by keeping a list of <<def_head,heads>> which reference the

-latest version on each branch; the gitlink:git-branch[1] command shows
+latest commit on each branch; the gitlink:git-branch[1] command shows

 you the list of branch heads:
 
 ------------------------------------------------
 you the list of branch heads:
 
 ------------------------------------------------


@@ -149,32 +145,27 @@ current branch:
 
 ------------------------------------------------
 $ git show
 
 ------------------------------------------------
 $ git show

-commit 2b5f6dcce5bf94b9b119e9ed8d537098ec61c3d2
-Author: Jamal Hadi Salim <hadi@cyberus.ca>
-Date:   Sat Dec 2 22:22:25 2006 -0800
-
-    [XFRM]: Fix aevent structuring to be more complete.
-    
-    aevents can not uniquely identify an SA. We break the ABI with this
-    patch, but consensus is that since it is not yet utilized by any
-    (known) application then it is fine (better do it now than later).
-    
-    Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
-    Signed-off-by: David S. Miller <davem@davemloft.net>
-
-diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
-index 8be626f..d7aac9d 100644
---- a/Documentation/networking/xfrm_sync.txt
-+++ b/Documentation/networking/xfrm_sync.txt
-@@ -47,10 +47,13 @@ aevent_id structure looks like:
+commit 17cf781661e6d38f737f15f53ab552f1e95960d7
+Author: Linus Torvalds <torvalds@ppc970.osdl.org.(none)>
+Date:   Tue Apr 19 14:11:06 2005 -0700
+
+    Remove duplicate getenv(DB_ENVIRONMENT) call
+
+    Noted by Tony Luck.
+
+diff --git a/init-db.c b/init-db.c
+index 65898fa..b002dc6 100644
+--- a/init-db.c
++++ b/init-db.c
+@@ -7,7 +7,7 @@

  
  

-    struct xfrm_aevent_id {
-              struct xfrm_usersa_id           sa_id;
-+             xfrm_address_t                  saddr;
-              __u32                           flags;
-+             __u32                           reqid;
-    };
-...
+ int main(int argc, char **argv)
+ {
+-      char *sha1_dir = getenv(DB_ENVIRONMENT), *path;
++      char *sha1_dir, *path;
+       int len, i;
+ 
+       if (mkdir(".git", 0755) < 0) {

 ------------------------------------------------
 
 As you can see, a commit shows who made the latest change, what they
 ------------------------------------------------
 
 As you can see, a commit shows who made the latest change, what they


@@ -890,7 +881,7 @@ $ git archive --format=tar --prefix=project/ HEAD | gzip >latest.tar.gz
 -------------------------------------------------
 
 will use HEAD to produce a tar archive in which each filename is
 -------------------------------------------------
 
 will use HEAD to produce a tar archive in which each filename is

-preceded by "prefix/".
+preceded by "project/".

 
 If you're releasing a new version of a software project, you may want
 to simultaneously make a changelog to include in the release
 
 If you're releasing a new version of a software project, you may want
 to simultaneously make a changelog to include in the release


@@ -923,7 +914,7 @@ they look OK.
 
 [[Finding-comments-with-given-content]]
 Finding commits referencing a file with given content
 
 [[Finding-comments-with-given-content]]
 Finding commits referencing a file with given content

------------------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

 
 Somebody hands you a copy of a file, and asks which commits modified a
 file such that it contained the given content either before or after the
 
 Somebody hands you a copy of a file, and asks which commits modified a
 file such that it contained the given content either before or after the


@@ -1100,20 +1091,14 @@ backup files made by your editor. Of course, 'not' tracking files with git
 is just a matter of 'not' calling "`git add`" on them. But it quickly becomes
 annoying to have these untracked files lying around; e.g. they make
 "`git add .`" and "`git commit -a`" practically useless, and they keep
 is just a matter of 'not' calling "`git add`" on them. But it quickly becomes
 annoying to have these untracked files lying around; e.g. they make
 "`git add .`" and "`git commit -a`" practically useless, and they keep

-showing up in the output of "`git status`", etc.
+showing up in the output of "`git status`".

 
 

-Git therefore provides "exclude patterns" for telling git which files to
-actively ignore. Exclude patterns are thoroughly explained in the
-gitlink:gitignore[5] manual page, but the heart of the concept is simply
-a list of files which git should ignore. Entries in the list may contain
-globs to specify multiple files, or may be prefixed by "`!`" to
-explicitly include (un-ignore) a previously excluded (ignored) file
-(i.e. later exclude patterns override earlier ones).  The following
-example should illustrate such patterns:
+You can tell git to ignore certain files by creating a file called .gitignore
+in the top level of your working directory, with contents such as:

 
 -------------------------------------------------
 # Lines starting with '#' are considered comments.
 
 -------------------------------------------------
 # Lines starting with '#' are considered comments.

-# Ignore foo.txt.
+# Ignore any file named foo.txt.

 foo.txt
 # Ignore (generated) html files,
 *.html
 foo.txt
 # Ignore (generated) html files,
 *.html


@@ -1123,41 +1108,20 @@ foo.txt
 *.[oa]
 -------------------------------------------------
 
 *.[oa]
 -------------------------------------------------
 

-The next question is where to put these exclude patterns so that git can
-find them. Git looks for exclude patterns in the following files:
-
-`.gitignore` files in your working tree:::
-          You may store multiple `.gitignore` files at various locations in your
-          working tree. Each `.gitignore` file is applied to the directory where
-          it's located, including its subdirectories. Furthermore, the
-          `.gitignore` files can be tracked like any other files in your working
-          tree; just do a "`git add .gitignore`" and commit. `.gitignore` is
-          therefore the right place to put exclude patterns that are meant to
-          be shared between all project participants, such as build output files
-          (e.g. `\*.o`), etc.
-`.git/info/exclude` in your repo:::
-          Exclude patterns in this file are applied to the working tree as a
-          whole. Since the file is not located in your working tree, it does
-          not follow push/pull/clone like `.gitignore` can do. This is therefore
-          the place to put exclude patterns that are local to your copy of the
-          repo (i.e. 'not' shared between project participants), such as
-          temporary backup files made by your editor (e.g. `\*~`), etc.
-The file specified by the `core.excludesfile` config directive:::
-          By setting the `core.excludesfile` config directive you can tell git
-          where to find more exclude patterns (see gitlink:git-config[1] for
-          more information on configuration options). This config directive
-          can be set in the per-repo `.git/config` file, in which case the
-          exclude patterns will apply to that repo only. Alternatively, you
-          can set the directive in the global `~/.gitconfig` file to apply
-          the exclude pattern to all your git repos. As with the above
-          `.git/info/exclude` (and, indeed, with git config directives in
-          general), this directive does not follow push/pull/clone, but remain
-          local to your repo(s).
-
-[NOTE]
-In addition to the above alternatives, there are git commands that can take
-exclude patterns directly on the command line. See gitlink:git-ls-files[1]
-for an example of this.
+See gitlink:gitignore[5] for a detailed explanation of the syntax.  You can
+also place .gitignore files in other directories in your working tree, and they
+will apply to those directories and their subdirectories.  The `.gitignore`
+files can be added to your repository like any other files (just run `git add
+.gitignore` and `git commit`, as usual), which is convenient when the exclude
+patterns (such as patterns matching build output files) would also make sense
+for other users who clone your repository.
+
+If you wish the exclude patterns to affect only certain repositories
+(instead of every repository for a given project), you may instead put
+them in a file in your repository named .git/info/exclude, or in any file
+specified by the `core.excludesfile` configuration variable.  Some git
+commands can also take exclude patterns directly on the command line.
+See gitlink:gitignore[5] for the details.

 
 [[how-to-merge]]
 How to merge
 
 [[how-to-merge]]
 How to merge


@@ -1528,9 +1492,9 @@ dangling tree b24c2473f1fd3d91352a624795be026d64c8841f
 -------------------------------------------------
 
 Dangling objects are not a problem.  At worst they may take up a little
 -------------------------------------------------
 
 Dangling objects are not a problem.  At worst they may take up a little

-extra disk space.  They can sometimes provide a last-resort method of
-recovery lost work--see <<dangling-objects>> for details.  However, if
-you want, you may remove them with gitlink:git-prune[1] or the --prune
+extra disk space.  They can sometimes provide a last-resort method for
+recovering lost work--see <<dangling-objects>> for details.  However, if
+you wish, you can remove them with gitlink:git-prune[1] or the --prune

 option to gitlink:git-gc[1]:
 
 -------------------------------------------------
 option to gitlink:git-gc[1]:
 
 -------------------------------------------------


@@ -1764,15 +1728,16 @@ taken from the message containing each patch.
 Public git repositories
 -----------------------
 
 Public git repositories
 -----------------------
 

-Another way to submit changes to a project is to tell the maintainer of
-that project to pull the changes from your repository using git-pull[1].
-In the section "<<getting-updates-with-git-pull, Getting updates with
-git pull>>" we described this as a way to get updates from the "main"
-repository, but it works just as well in the other direction.
+Another way to submit changes to a project is to tell the maintainer
+of that project to pull the changes from your repository using
+gitlink:git-pull[1].  In the section "<<getting-updates-with-git-pull,
+Getting updates with git pull>>" we described this as a way to get
+updates from the "main" repository, but it works just as well in the
+other direction.

 
 If you and the maintainer both have accounts on the same machine, then
 you can just pull changes from each other's repositories directly;
 
 If you and the maintainer both have accounts on the same machine, then
 you can just pull changes from each other's repositories directly;

-commands that accepts repository URLs as arguments will also accept a
+commands that accept repository URLs as arguments will also accept a

 local directory name:
 
 -------------------------------------------------
 local directory name:
 
 -------------------------------------------------


@@ -1780,6 +1745,15 @@ $ git clone /path/to/repository
 $ git pull /path/to/other/repository
 -------------------------------------------------
 
 $ git pull /path/to/other/repository
 -------------------------------------------------
 

+or an ssh url:
+
+-------------------------------------------------
+$ git clone ssh://yourhost/~you/repository
+-------------------------------------------------
+
+For projects with few developers, or for synchronizing a few private
+repositories, this may be all you need.
+

 However, the more common way to do this is to maintain a separate public
 repository (usually on a different host) for others to pull changes
 from.  This is usually more convenient, and allows you to cleanly
 However, the more common way to do this is to maintain a separate public
 repository (usually on a different host) for others to pull changes
 from.  This is usually more convenient, and allows you to cleanly


@@ -1802,6 +1776,8 @@ like this:
         |               they push             V
   their public repo <------------------- their repo
 
         |               they push             V
   their public repo <------------------- their repo
 

+We explain how to do this in the following sections.
+

 [[setting-up-a-public-repository]]
 Setting up a public repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 [[setting-up-a-public-repository]]
 Setting up a public repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


@@ -1913,6 +1889,12 @@ proceeding the branch name by a plus sign:
 $ git push ssh://yourserver.com/~you/proj.git +master
 -------------------------------------------------
 
 $ git push ssh://yourserver.com/~you/proj.git +master
 -------------------------------------------------
 

+Note that the target of a "push" is normally a
+<<def_bare_repository,bare>> repository.  You can also push to a
+repository that has a checked-out working tree, but the working tree
+will not be updated by the push.  This may lead to unexpected results if
+the branch you push to is the currently checked-out branch!
+

 As with git-fetch, you may also set up configuration options to
 save typing; so, for example, after
 
 As with git-fetch, you may also set up configuration options to
 save typing; so, for example, after
 


@@ -2008,7 +1990,8 @@ $ cd work
 Linus's tree will be stored in the remote branch named origin/master,
 and can be updated using gitlink:git-fetch[1]; you can track other
 public trees using gitlink:git-remote[1] to set up a "remote" and
 Linus's tree will be stored in the remote branch named origin/master,
 and can be updated using gitlink:git-fetch[1]; you can track other
 public trees using gitlink:git-remote[1] to set up a "remote" and

-git-fetch[1] to keep them up-to-date; see <<repositories-and-branches>>.
+gitlink:git-fetch[1] to keep them up-to-date; see
+<<repositories-and-branches>>.

 
 Now create the branches in which you are going to work; these start out
 at the current tip of origin/master branch, and should be set up (using
 
 Now create the branches in which you are going to work; these start out
 at the current tip of origin/master branch, and should be set up (using


@@ -2757,8 +2740,8 @@ As a result, the general consistency of an object can always be tested
 independently of the contents or the type of the object: all objects can
 be validated by verifying that (a) their hashes match the content of the
 file and (b) the object successfully inflates to a stream of bytes that
 independently of the contents or the type of the object: all objects can
 be validated by verifying that (a) their hashes match the content of the
 file and (b) the object successfully inflates to a stream of bytes that

-forms a sequence of <ascii type without space> + <space> + <ascii decimal
-size> + <byte\0> + <binary object data>. 
+forms a sequence of <ascii type without space> {plus} <space> {plus} <ascii decimal
+size> {plus} <byte\0> {plus} <binary object data>.

 
 The structured objects can further have their structure and
 connectivity to other objects verified. This is generally done with
 
 The structured objects can further have their structure and
 connectivity to other objects verified. This is generally done with