Make use of stat.ctime configurable
[gitweb.git] / Documentation / user-manual.txt
index 64a820bf60ae5da8aaaac5fd72c169b8dd381c89..c5641af19059f5531e43bd4d4ff495548030fe98 100644 (file)
@@ -18,7 +18,7 @@ People needing to do actual development will also want to read
 Further chapters cover more specialized topics.
 
 Comprehensive reference documentation is available through the man
-pages.  For a command such as "git clone", just use
+pages.  For a command such as "git clone <repo>", just use
 
 ------------------------------------------------
 $ man git-clone
@@ -178,7 +178,7 @@ As you can see, a commit shows who made the latest change, what they
 did, and why.
 
 Every commit has a 40-hexdigit id, sometimes called the "object name" or the
-"SHA1 id", shown on the first line of the "git show" output.  You can usually
+"SHA1 id", shown on the first line of the "git-show" output.  You can usually
 refer to a commit by a shorter name, such as a tag or a branch name, but this
 longer name can also be useful.  Most importantly, it is a globally unique
 name for this commit: so if you tell somebody else the object name (for
@@ -390,7 +390,7 @@ references with the same shorthand name, see the "SPECIFYING
 REVISIONS" section of linkgit:git-rev-parse[1].
 
 [[Updating-a-repository-with-git-fetch]]
-Updating a repository with git fetch
+Updating a repository with git-fetch
 ------------------------------------
 
 Eventually the developer cloned from will do additional work in her
@@ -417,7 +417,7 @@ $ git fetch linux-nfs
 -------------------------------------------------
 
 New remote-tracking branches will be stored under the shorthand name
-that you gave "git remote add", in this case linux-nfs:
+that you gave "git-remote add", in this case linux-nfs:
 
 -------------------------------------------------
 $ git branch -r
@@ -518,7 +518,7 @@ $ git bisect visualize
 -------------------------------------------------
 
 which will run gitk and label the commit it chose with a marker that
-says "bisect".  Chose a safe-looking commit nearby, note its commit
+says "bisect".  Choose a safe-looking commit nearby, note its commit
 id, and check it out with:
 
 -------------------------------------------------
@@ -1048,7 +1048,7 @@ $ git diff
 
 shows the difference between the working tree and the index file.
 
-Note that "git add" always adds just the current contents of a file
+Note that "git-add" always adds just the current contents of a file
 to the index; further changes to the same file will be ignored unless
 you run git-add on the file again.
 
@@ -1111,7 +1111,7 @@ Ignoring files
 A project will often generate files that you do 'not' want to track with git.
 This typically includes files generated by a build process or temporary
 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
+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`".
@@ -1303,7 +1303,7 @@ $ git diff -3 file.txt            # diff against stage 3
 $ git diff --theirs file.txt   # same as the above.
 -------------------------------------------------
 
-The linkgit:git-log[1] and gitk[1] commands also provide special help
+The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
 for merges:
 
 -------------------------------------------------
@@ -1449,7 +1449,7 @@ Checking out an old version of a file
 
 In the process of undoing a previous bad change, you may find it
 useful to check out an older version of a particular file using
-linkgit:git-checkout[1].  We've used git checkout before to switch
+linkgit:git-checkout[1].  We've used git-checkout before to switch
 branches, but it has quite different behavior if it is given a path
 name: the command
 
@@ -1651,7 +1651,7 @@ Sharing development with others
 ===============================
 
 [[getting-updates-with-git-pull]]
-Getting updates with git pull
+Getting updates with git-pull
 -----------------------------
 
 After you clone a repository and make a few changes of your own, you
@@ -1770,7 +1770,7 @@ 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
 linkgit:git-pull[1].  In the section "<<getting-updates-with-git-pull,
-Getting updates with git pull>>" we described this as a way to get
+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.
 
@@ -1879,8 +1879,7 @@ $ chmod a+x hooks/post-update
 -------------------------------------------------
 
 (For an explanation of the last two lines, see
-linkgit:git-update-server-info[1], and the documentation
-linkgit:githooks[5][Hooks used by git].)
+linkgit:git-update-server-info[1] and linkgit:githooks[5].)
 
 Advertise the URL of proj.git.  Anybody else should then be able to
 clone or pull from that URL, for example with a command line like:
@@ -1964,10 +1963,10 @@ error: failed to push to 'ssh://yourserver.com/~you/proj.git'
 
 This can happen, for example, if you:
 
-       - use `git reset --hard` to remove already-published commits, or
-       - use `git commit --amend` to replace already-published commits
+       - use `git-reset --hard` to remove already-published commits, or
+       - use `git-commit --amend` to replace already-published commits
          (as in <<fixing-a-mistake-by-rewriting-history>>), or
-       - use `git rebase` to rebase any already-published commits (as
+       - use `git-rebase` to rebase any already-published commits (as
          in <<using-git-rebase>>).
 
 You may force git-push to perform the update anyway by preceding the
@@ -1989,10 +1988,10 @@ intend to manage the branch.
 
 It's also possible for a push to fail in this way when other people have
 the right to push to the same repository.  In that case, the correct
-solution is to retry the push after first updating your work by either a
-pull or a fetch followed by a rebase; see the
+solution is to retry the push after first updating your work: either by a
+pull, or by a fetch followed by a rebase; see the
 <<setting-up-a-shared-repository,next section>> and
-linkgit:gitcvs-migration[7][git for CVS users] for more.
+linkgit:gitcvs-migration[7] for more.
 
 [[setting-up-a-shared-repository]]
 Setting up a shared repository
@@ -2001,7 +2000,7 @@ Setting up a shared repository
 Another way to collaborate is by using a model similar to that
 commonly used in CVS, where several developers with special rights
 all push to and pull from a single shared repository.  See
-linkgit:gitcvs-migration[7][git for CVS users] for instructions on how to
+linkgit:gitcvs-migration[7] for instructions on how to
 set this up.
 
 However, while there is nothing wrong with git's support for shared
@@ -2171,7 +2170,7 @@ they are for, or what status they are in.  To get a reminder of what
 changes are in a specific branch, use:
 
 -------------------------------------------------
-$ git log linux..branchname | git-shortlog
+$ git log linux..branchname | git shortlog
 -------------------------------------------------
 
 To see whether it has already been merged into the test or release branches,
@@ -2432,7 +2431,7 @@ $ git rebase origin
 -------------------------------------------------
 
 This will remove each of your commits from mywork, temporarily saving
-them as patches (in a directory named ".dotest"), update mywork to
+them as patches (in a directory named ".git/rebase-apply"), update mywork to
 point at the latest version of origin, then apply each of the saved
 patches to the new mywork.  The result will look like:
 
@@ -2444,8 +2443,8 @@ patches to the new mywork.  The result will look like:
 ................................................
 
 In the process, it may discover conflicts.  In that case it will stop
-and allow you to fix the conflicts; after fixing conflicts, use "git
-add" to update the index with those contents, and then, instead of
+and allow you to fix the conflicts; after fixing conflicts, use "git-add"
+to update the index with those contents, and then, instead of
 running git-commit, just run
 
 -------------------------------------------------
@@ -2701,8 +2700,8 @@ master branch.  In more detail:
 git fetch and fast-forwards
 ---------------------------
 
-In the previous example, when updating an existing branch, "git
-fetch" checks to make sure that the most recent commit on the remote
+In the previous example, when updating an existing branch, "git-fetch"
+checks to make sure that the most recent commit on the remote
 branch is a descendant of the most recent commit on your copy of the
 branch before updating your copy of the branch to point at the new
 commit.  Git calls this process a <<fast-forwards,fast forward>>.
@@ -2727,7 +2726,7 @@ resulting in a situation like:
             o--o--o <-- new head of the branch
 ................................................
 
-In this case, "git fetch" will fail, and print out a warning.
+In this case, "git-fetch" will fail, and print out a warning.
 
 In that case, you can still force git to update to the new head, as
 described in the following section.  However, note that in the
@@ -2736,7 +2735,7 @@ unless you've already created a reference of your own pointing to
 them.
 
 [[forcing-fetch]]
-Forcing git fetch to do non-fast-forward updates
+Forcing git-fetch to do non-fast-forward updates
 ------------------------------------------------
 
 If git fetch fails because the new head of a branch is not a
@@ -2811,7 +2810,7 @@ You can also add a "+" to force the update each time:
 $ git config remote.example.fetch +master:ref/remotes/example/master
 -------------------------------------------------
 
-Don't do this unless you're sure you won't mind "git fetch" possibly
+Don't do this unless you're sure you won't mind "git-fetch" possibly
 throwing away commits on mybranch.
 
 Also note that all of the above configuration can be performed by
@@ -2862,7 +2861,7 @@ There are four different types of objects: "blob", "tree", "commit", and
 "tag".
 
 - A <<def_blob_object,"blob" object>> is used to store file data.
-- A <<def_tree_object,"tree" object>> is an object that ties one or more
+- A <<def_tree_object,"tree" object>> ties one or more
   "blob" objects into a directory structure. In addition, a tree object
   can refer to other tree objects, thus creating a directory hierarchy.
 - A <<def_commit_object,"commit" object>> ties such directory hierarchies
@@ -3037,7 +3036,7 @@ Tag Object
 
 A tag object contains an object, object type, tag name, the name of the
 person ("tagger") who created the tag, and a message, which may contain
-a signature, as can be seen using the linkgit:git-cat-file[1]:
+a signature, as can be seen using linkgit:git-cat-file[1]:
 
 ------------------------------------------------
 $ git cat-file tag v1.5.0
@@ -3107,7 +3106,7 @@ $ git prune
 
 to remove any of the "loose" objects that are now contained in the
 pack.  This will also remove any unreferenced objects (which may be
-created when, for example, you use "git reset" to remove a commit).
+created when, for example, you use "git-reset" to remove a commit).
 You can verify that the loose objects are gone by looking at the
 .git/objects directory or by running
 
@@ -3136,7 +3135,7 @@ branch still exists, as does everything it pointed to. The branch
 pointer itself just doesn't, since you replaced it with another one.
 
 There are also other situations that cause dangling objects. For
-example, a "dangling blob" may arise because you did a "git add" of a
+example, a "dangling blob" may arise because you did a "git-add" of a
 file, but then, before you actually committed it and made it part of the
 bigger picture, you changed something else in that file and committed
 that *updated* thing--the old state that you added originally ends up
@@ -3186,7 +3185,7 @@ Usually, dangling blobs and trees aren't very interesting. They're
 almost always the result of either being a half-way mergebase (the blob
 will often even have the conflict markers from a merge in it, if you
 have had conflicting merges that you fixed up by hand), or simply
-because you interrupted a "git fetch" with ^C or something like that,
+because you interrupted a "git-fetch" with ^C or something like that,
 leaving _some_ of the new objects in the object database, but just
 dangling and useless.
 
@@ -3235,7 +3234,7 @@ it is with linkgit:git-fsck[1]; this may be time-consuming.
 Assume the output looks like this:
 
 ------------------------------------------------
-$ git-fsck --full
+$ git fsck --full
 broken link from    tree 2d9263c6d23595e7cb2a21e5ebbb53655278dff8
               to    blob 4b9458b3786228369c63936db65827de3cc06200
 missing blob 4b9458b3786228369c63936db65827de3cc06200
@@ -3465,14 +3464,14 @@ done
 
 NOTE: Do not use local URLs here if you plan to publish your superproject!
 
-See what files `git submodule` created:
+See what files `git-submodule` created:
 
 -------------------------------------------------
 $ ls -a
 .  ..  .git  .gitmodules  a  b  c  d
 -------------------------------------------------
 
-The `git submodule add` command does a couple of things:
+The `git-submodule add` command does a couple of things:
 
 - It clones the submodule under the current directory and by default checks out
   the master branch.
@@ -3518,7 +3517,7 @@ init` to add the submodule repository URLs to `.git/config`:
 $ git submodule init
 -------------------------------------------------
 
-Now use `git submodule update` to clone the repositories and check out the
+Now use `git-submodule update` to clone the repositories and check out the
 commits specified in the superproject:
 
 -------------------------------------------------
@@ -3528,8 +3527,8 @@ $ ls -a
 .  ..  .git  a.txt
 -------------------------------------------------
 
-One major difference between `git submodule update` and `git submodule add` is
-that `git submodule update` checks out a specific commit, rather than the tip
+One major difference between `git-submodule update` and `git-submodule add` is
+that `git-submodule update` checks out a specific commit, rather than the tip
 of a branch. It's like checking out a tag: the head is detached, so you're not
 working on a branch.
 
@@ -3695,7 +3694,7 @@ removed. The only thing `--remove` means is that update-index will be
 considering a removed file to be a valid thing, and if the file really
 does not exist any more, it will update the index accordingly.
 
-As a special case, you can also do `git-update-index --refresh`, which
+As a special case, you can also do `git update-index --refresh`, which
 will refresh the "stat" information of each index to match the current
 stat information. It will 'not' update the object status itself, and
 it will only update the fields that are used to quickly test whether
@@ -3730,7 +3729,7 @@ unsaved state that you might want to restore later!) your current
 index.  Normal operation is just
 
 -------------------------------------------------
-$ git-read-tree <sha1 of tree>
+$ git read-tree <sha1 of tree>
 -------------------------------------------------
 
 and your index file will now be equivalent to the tree that you saved
@@ -3753,7 +3752,7 @@ index file with read-tree, and then you need to check out the result
 with
 
 -------------------------------------------------
-$ git-checkout-index filename
+$ git checkout-index filename
 -------------------------------------------------
 
 or, if you want to check out all of the index, use `-a`.
@@ -3771,7 +3770,7 @@ from one representation to the other:
 Tying it all together
 ~~~~~~~~~~~~~~~~~~~~~
 
-To commit a tree you have instantiated with "git-write-tree", you'd
+To commit a tree you have instantiated with "git write-tree", you'd
 create a "commit" object that refers to that tree and the history
 behind it--most notably the "parent" commits that preceded it in
 history.
@@ -3790,7 +3789,7 @@ You create a commit object by giving it the tree that describes the
 state at the time of the commit, and a list of parents:
 
 -------------------------------------------------
-$ git-commit-tree <tree> -p <parent> [-p <parent2> ..]
+$ git commit-tree <tree> -p <parent> [-p <parent2> ..]
 -------------------------------------------------
 
 and then giving the reason for the commit on stdin (either through
@@ -3853,14 +3852,14 @@ linkgit:git-cat-file[1] to examine details about the
 object:
 
 -------------------------------------------------
-$ git-cat-file -t <objectname>
+$ git cat-file -t <objectname>
 -------------------------------------------------
 
 shows the type of the object, and once you have the type (which is
 usually implicit in where you find the object), you can use
 
 -------------------------------------------------
-$ git-cat-file blob|tree|commit|tag <objectname>
+$ git cat-file blob|tree|commit|tag <objectname>
 -------------------------------------------------
 
 to show its contents. NOTE! Trees have binary content, and as a result
@@ -3874,7 +3873,7 @@ follow the convention of having the top commit name in `.git/HEAD`,
 you can do
 
 -------------------------------------------------
-$ git-cat-file commit HEAD
+$ git cat-file commit HEAD
 -------------------------------------------------
 
 to see what the top commit was.
@@ -3898,7 +3897,7 @@ To get the "base" for the merge, you first look up the common parent
 of two commits with
 
 -------------------------------------------------
-$ git-merge-base <commit1> <commit2>
+$ git merge-base <commit1> <commit2>
 -------------------------------------------------
 
 which will return you the commit they are both based on.  You should
@@ -3906,7 +3905,7 @@ now look up the "tree" objects of those commits, which you can easily
 do with (for example)
 
 -------------------------------------------------
-$ git-cat-file commit <commitname> | head -1
+$ git cat-file commit <commitname> | head -1
 -------------------------------------------------
 
 since the tree object information is always the first line in a commit
@@ -3923,12 +3922,12 @@ you have in your current index anyway).
 To do the merge, do
 
 -------------------------------------------------
-$ git-read-tree -m -u <origtree> <yourtree> <targettree>
+$ git read-tree -m -u <origtree> <yourtree> <targettree>
 -------------------------------------------------
 
 which will do all trivial merge operations for you directly in the
 index file, and you can just write the result out with
-`git-write-tree`.
+`git write-tree`.
 
 
 [[merging-multiple-trees-2]]
@@ -3942,18 +3941,18 @@ entries" in it. Such an index tree can 'NOT' be written out to a tree
 object, and you will have to resolve any such merge clashes using
 other tools before you can write out the result.
 
-You can examine such index state with `git-ls-files --unmerged`
+You can examine such index state with `git ls-files --unmerged`
 command.  An example:
 
 ------------------------------------------------
-$ git-read-tree -m $orig HEAD $target
-$ git-ls-files --unmerged
+$ git read-tree -m $orig HEAD $target
+$ git ls-files --unmerged
 100644 263414f423d0e4d70dae8fe53fa34614ff3e2860 1      hello.c
 100644 06fa6a24256dc7e560efa5687fa84b51f0263c3a 2      hello.c
 100644 cc44c73eb783565da5831b4d820c962954019b69 3      hello.c
 ------------------------------------------------
 
-Each line of the `git-ls-files --unmerged` output begins with
+Each line of the `git ls-files --unmerged` output begins with
 the blob mode bits, blob SHA1, 'stage number', and the
 filename.  The 'stage number' is git's way to say which tree it
 came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`
@@ -3971,9 +3970,9 @@ program, e.g.  `diff3`, `merge`, or git's own merge-file, on
 the blob objects from these three stages yourself, like this:
 
 ------------------------------------------------
-$ git-cat-file blob 263414f... >hello.c~1
-$ git-cat-file blob 06fa6a2... >hello.c~2
-$ git-cat-file blob cc44c73... >hello.c~3
+$ git cat-file blob 263414f... >hello.c~1
+$ git cat-file blob 06fa6a2... >hello.c~2
+$ git cat-file blob cc44c73... >hello.c~3
 $ git merge-file hello.c~2 hello.c~1 hello.c~3
 ------------------------------------------------
 
@@ -3984,23 +3983,23 @@ merge result for this file is by:
 
 -------------------------------------------------
 $ mv -f hello.c~2 hello.c
-$ git-update-index hello.c
+$ git update-index hello.c
 -------------------------------------------------
 
-When a path is in unmerged state, running `git-update-index` for
+When a path is in the "unmerged" state, running `git-update-index` for
 that path tells git to mark the path resolved.
 
 The above is the description of a git merge at the lowest level,
 to help you understand what conceptually happens under the hood.
-In practice, nobody, not even git itself, uses three `git-cat-file`
-for this.  There is `git-merge-index` program that extracts the
+In practice, nobody, not even git itself, runs `git-cat-file` three times
+for this.  There is `git-merge-index` program that extracts the
 stages to temporary files and calls a "merge" script on it:
 
 -------------------------------------------------
-$ git-merge-index git-merge-one-file hello.c
+$ git merge-index git-merge-one-file hello.c
 -------------------------------------------------
 
-and that is what higher level `git merge -s resolve` is implemented with.
+and that is what higher level `git-merge -s resolve` is implemented with.
 
 [[hacking-git]]
 Hacking git
@@ -4062,7 +4061,7 @@ Note that terminology has changed since that revision.  For example, the
 README in that revision uses the word "changeset" to describe what we
 now call a <<def_commit_object,commit>>.
 
-Also, we do not call it "cache" any more, but "index", however, the
+Also, we do not call it "cache" any more, but rather "index"; however, the
 file is still called `cache.h`.  Remark: Not much reason to change it now,
 especially since there is no good single name for it anyway, because it is
 basically _the_ header file which is included by _all_ of Git's C sources.
@@ -4096,7 +4095,7 @@ functions like `get_sha1_basic()` or the likes.
 This is just to get you into the groove for the most libified part of Git:
 the revision walker.
 
-Basically, the initial version of `git log` was a shell script:
+Basically, the initial version of `git-log` was a shell script:
 
 ----------------------------------------------------------------
 $ git-rev-list --pretty $(git-rev-parse --default HEAD "$@") | \
@@ -4128,10 +4127,10 @@ commits one by one with the function `get_revision()`.
 
 If you are interested in more details of the revision walking process,
 just have a look at the first implementation of `cmd_log()`; call
-`git-show v1.3.0{tilde}155^2{tilde}4` and scroll down to that function (note that you
+`git show v1.3.0{tilde}155^2{tilde}4` and scroll down to that function (note that you
 no longer need to call `setup_pager()` directly).
 
-Nowadays, `git log` is a builtin, which means that it is _contained_ in the
+Nowadays, `git-log` is a builtin, which means that it is _contained_ in the
 command `git`.  The source side of a builtin is
 
 - a function called `cmd_<bla>`, typically defined in `builtin-<bla>.c`,
@@ -4147,7 +4146,7 @@ since they share quite a bit of code.  In that case, the commands which are
 _not_ named like the `.c` file in which they live have to be listed in
 `BUILT_INS` in the `Makefile`.
 
-`git log` looks more complicated in C than it does in the original script,
+`git-log` looks more complicated in C than it does in the original script,
 but that allows for a much greater flexibility and performance.
 
 Here again it is a good point to take a pause.
@@ -4158,9 +4157,9 @@ the organization of Git (after you know the basic concepts).
 So, think about something which you are interested in, say, "how can I
 access a blob just knowing the object name of it?".  The first step is to
 find a Git command with which you can do it.  In this example, it is either
-`git show` or `git cat-file`.
+`git-show` or `git-cat-file`.
 
-For the sake of clarity, let's stay with `git cat-file`, because it
+For the sake of clarity, let's stay with `git-cat-file`, because it
 
 - is plumbing, and
 
@@ -4219,10 +4218,10 @@ To find out how the result can be used, just read on in `cmd_cat_file()`:
 -----------------------------------
 
 Sometimes, you do not know where to look for a feature.  In many such cases,
-it helps to search through the output of `git log`, and then `git show` the
+it helps to search through the output of `git log`, and then `git-show` the
 corresponding commit.
 
-Example: If you know that there was some test case for `git bundle`, but
+Example: If you know that there was some test case for `git-bundle`, but
 do not remember where it was (yes, you _could_ `git grep bundle t/`, but that
 does not illustrate the point!):