From: Junio C Hamano Date: Sun, 20 May 2007 07:19:30 +0000 (-0700) Subject: Merge branch 'maint' to synchronize with 1.5.1.6 X-Git-Tag: v1.5.2~2 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/03f6db0ec058ca1d34672a3100293c3bf56c3b6b?ds=inline;hp=-c Merge branch 'maint' to synchronize with 1.5.1.6 * maint: GIT 1.5.1.6 git-svn: don't minimize-url when doing an init that tracks multiple paths git-svn: avoid crashing svnserve when creating new directories user-manual: Add section on ignoring files user-manual: finding commits referencing given file content user-manual: discourage shared repository tutorial: revise index introduction tutorials: add user-manual links Conflicts: GIT-VERSION-GEN RelNotes --- 03f6db0ec058ca1d34672a3100293c3bf56c3b6b diff --combined Documentation/user-manual.txt index c4bff474dd,534ece464b..52247aa713 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@@ -921,6 -921,22 +921,22 @@@ echo "git diff --stat --summary -M v$la 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 +1089,75 @@@ description. Tools that turn commits i 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 +1864,7 @@@ $ chmod a+x hooks/post-updat (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 +1939,30 @@@ Setting up a shared repositor 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 +3922,6 @@@ Think about how to create a clear chapt 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/?