Merge branch 'maint-1.5.1' into maint
[gitweb.git] / Documentation / user-manual.txt
index f4843f4e907f9467f6bbdfc519763d789bc20520..52247aa7134345e94b3c2cc131d33224073f6eeb 100644 (file)
@@ -921,6 +921,22 @@ echo "git diff --stat --summary -M v$last v$new > ../diffstat-$new"
 and then he just cut-and-pastes the output commands after verifying that
 they look OK.
 
+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
+commit.  You can find out with this:
+
+-------------------------------------------------
+$  git log --raw -r --abbrev=40 --pretty=oneline -- filename |
+       grep -B 1 `git hash-object filename`
+-------------------------------------------------
+
+Figuring out why this works is left as an exercise to the (advanced)
+student.  The gitlink:git-log[1], gitlink:git-diff-tree[1], and
+gitlink:git-hash-object[1] man pages may prove helpful.
+
 [[Developing-with-git]]
 Developing with git
 ===================
@@ -1073,6 +1089,75 @@ description.  Tools that turn commits into email, for example, use
 the first line on the Subject line and the rest of the commit in the
 body.
 
+[[ignoring-files]]
+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
+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.
+
+Git therefore provides "exclude patterns" for telling git which files to
+actively ignore. Exclude patterns are thoroughly explained in the
+"Exclude Patterns" section of the gitlink:git-ls-files[1] 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:
+
+-------------------------------------------------
+# Lines starting with '#' are considered comments.
+# Ignore foo.txt.
+foo.txt
+# Ignore (generated) html files,
+*.html
+# except foo.html which is maintained by hand.
+!foo.html
+# Ignore objects and archives.
+*.[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.
+
 [[how-to-merge]]
 How to merge
 ------------
@@ -1779,7 +1864,7 @@ $ chmod a+x hooks/post-update
 
 (For an explanation of the last two lines, see
 gitlink:git-update-server-info[1], and the documentation
-link:hooks.txt[Hooks used by git].)
+link:hooks.html[Hooks used by git].)
 
 Advertise the url of proj.git.  Anybody else should then be able to
 clone or pull from that url, for example with a commandline like:
@@ -1854,9 +1939,30 @@ 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
-link:cvs-migration.txt[git for CVS users] for instructions on how to
+link:cvs-migration.html[git for CVS users] for instructions on how to
 set this up.
 
+However, while there is nothing wrong with git's support for shared
+repositories, this mode of operation is not generally recommended,
+simply because the mode of collaboration that git supports--by
+exchanging patches and pulling from public repositories--has so many
+advantages over the central shared repository:
+
+       - Git's ability to quickly import and merge patches allows a
+         single maintainer to process incoming changes even at very
+         high rates.  And when that becomes too much, git-pull provides
+         an easy way for that maintainer to delegate this job to other
+         maintainers while still allowing optional review of incoming
+         changes.
+       - Since every developer's repository has the same complete copy
+         of the project history, no repository is special, and it is
+         trivial for another developer to take over maintenance of a
+         project, either by mutual agreement, or because a maintainer
+         becomes unresponsive or difficult to work with.
+       - The lack of a central group of "committers" means there is
+         less need for formal decisions about who is "in" and who is
+         "out".
+
 [[setting-up-gitweb]]
 Allowing web browsing of a repository
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -3816,8 +3922,6 @@ Think about how to create a clear chapter dependency graph that will
 allow people to get to important topics without necessarily reading
 everything in between.
 
-Say something about .gitignore.
-
 Scan Documentation/ for other stuff left out; in particular:
        howto's
        some of technical/?