diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/Makefile | 21 | ||||
| -rw-r--r-- | Documentation/RelNotes-1.5.2.txt | 119 | ||||
| -rw-r--r-- | Documentation/SubmittingPatches | 3 | ||||
| -rw-r--r-- | Documentation/asciidoc.conf | 19 | ||||
| -rw-r--r-- | Documentation/config.txt | 26 | ||||
| -rw-r--r-- | Documentation/git-archive.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-bisect.txt | 19 | ||||
| -rw-r--r-- | Documentation/git-cvsserver.txt | 107 | ||||
| -rw-r--r-- | Documentation/git-format-patch.txt | 17 | ||||
| -rw-r--r-- | Documentation/git-fsck.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-read-tree.txt | 14 | ||||
| -rw-r--r-- | Documentation/git-rev-list.txt | 28 | ||||
| -rw-r--r-- | Documentation/git-rm.txt | 9 | ||||
| -rw-r--r-- | Documentation/pretty-formats.txt | 1 |
14 files changed, 375 insertions, 19 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index ad87736b0c..a637d8d559 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -65,6 +65,11 @@ install: man $(INSTALL) -m644 $(DOC_MAN7) $(DESTDIR)$(man7dir) +../GIT-VERSION-FILE: .FORCE-GIT-VERSION-FILE + $(MAKE) -C ../ GIT-VERSION-FILE + +-include ../GIT-VERSION-FILE + # # Determine "include::" file references in asciidoc files. # @@ -94,17 +99,25 @@ cmd-list.made: cmd-list.perl $(MAN1_TXT) git.7 git.html: git.txt core-intro.txt clean: - rm -f *.xml *.html *.1 *.7 howto-index.txt howto/*.html doc.dep + rm -f *.xml *.xml+ *.html *.html+ *.1 *.7 howto-index.txt howto/*.html doc.dep rm -f $(cmds_txt) *.made %.html : %.txt - $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf $(ASCIIDOC_EXTRA) $< + rm -f $@+ $@ + $(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \ + $(ASCIIDOC_EXTRA) -o - $< | \ + sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+ + mv $@+ $@ %.1 %.7 : %.xml xmlto -m callouts.xsl man $< %.xml : %.txt - $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf $< + rm -f $@+ $@ + $(ASCIIDOC) -b docbook -d manpage -f asciidoc.conf \ + $(ASCIIDOC_EXTRA) -o - $< | \ + sed -e 's/@@GIT_VERSION@@/$(GIT_VERSION)/g' >$@+ + mv $@+ $@ user-manual.xml: user-manual.txt user-manual.conf $(ASCIIDOC) -b docbook -d book $< @@ -135,3 +148,5 @@ install-webdoc : html quick-install: sh ./install-doc-quick.sh $(DOC_REF) $(mandir) + +.PHONY: .FORCE-GIT-VERSION-FILE diff --git a/Documentation/RelNotes-1.5.2.txt b/Documentation/RelNotes-1.5.2.txt new file mode 100644 index 0000000000..d93da608c7 --- /dev/null +++ b/Documentation/RelNotes-1.5.2.txt @@ -0,0 +1,119 @@ +GIT v1.5.2 Release Notes (draft) +======================== + +Updates since v1.5.1 +-------------------- + +* New commands and options. + + - "git bisect start" can optionally take a single bad commit and + zero or more good commits on the command line. + + - "git shortlog" can optionally be told to wrap its output. + + - "subtree" merge strategy allows another project to be merged in as + your subdirectory. + + - "git format-patch" learned a new --subject-prefix=<string> + option, to override the built-in "[PATCH]". + +* Updated behavior of existing commands. + + - "git diff --stat" shows size of preimage and postimage blobs + for binary contents. Earlier it only said "Bin". + + - "git lost-found" shows stuff that are unreachable except + from reflogs. + + - "git checkout branch^0" now detaches HEAD at the tip commit + on the named branch, instead of just switching to the + branch (use "git checkout branch" to switch to the branch, + as before). + + - "git bisect next" can be used after giving only a bad commit + without giving a good one (this starts bisection half-way to + the root commit). We used to refuse to operate without a + good and a bad commit. + + - "git push", when pushing into more than one repository, does + not stop at the first error. + + - "git archive" does not insist you to give --format parameter + anymore; it defaults to "tar". + +* Builds + + - git-p4import has never been installed; now there is an + installation option to do so. + + - gitk and git-gui can be configured out. + + - Generated documentation pages automatically get version + information from GIT_VERSION + + - Parallel build with "make -j" descending into subdirectory + was fixed. + +* Performance Tweaks + + - optimized "git-rev-list --bisect" (hence "git-bisect"). + + - optimized "git-add $path" in a large directory, most of + whose contents are ignored. + + +Fixes since v1.5.1 +------------------ + +The following are all in v1.5.1.x series, unless otherwise noted. + +* Documentation updates + + - Various documentation updates from J. Bruce Fields, Frank + Lichtenheld, Alex Riesen and others. Andrew Ruder started a + war on undocumented options. + +* Bugfixes + + - "git diff a/ b/" incorrectly fell in "diff between two + filesystem objects" codepath, when the user most likely + wanted to limit the extent of output to two tracked + directories. + + - git-quiltimport had the same bug as we fixed for + git-applymbox in v1.5.1.1 -- it gave an alarming "did not + have any patch" message (but did not actually fail and was + harmless). + + - various git-svn fixes. + + - Sample update hook incorrectly always refused requests to + delete branches through push. + + - git-blame on a very long working tree path had buffer + overrun problem. + + - Switching branches with "git checkout" refused to work when + a path changes from a file to a directory between the + current branch and the new branch, in order not to lose + possible local changes in the directory that is being turned + into a file with the switch. We now allow such a branch + switch after making sure that there is no locally modified + file nor un-ignored file in the directory. This has not + been backported to 1.5.1.x series, as it is rather an + intrusive change. + + - Merging branches that have a file in one and a directory in + another at the same path used to get quite confused. We + handle such a case a bit more carefully, even though that is + still left as a conflict for the user to sort out. This + will not be backported to 1.5.1.x series, as it is rather an + intrusive change. + +* Performance Tweaks + +-- +exec >/var/tmp/1 +O=v1.5.1.1-158-g86da9de +echo O=`git describe refs/heads/master` +git shortlog --no-merges $O..refs/heads/master ^refs/heads/maint diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 131bcff9b2..2386f496ee 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -22,6 +22,9 @@ Checklist (and a short version for the impatient): - provide additional information (which is unsuitable for the commit message) between the "---" and the diffstat - send the patch to the list _and_ the maintainer + - if you change, add, or remove a command line option or + make some other user interface change, the associated + documentation should be updated as well. Long version: diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 44b1ce4c6b..fa7dc94845 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -31,6 +31,25 @@ ifdef::backend-docbook[] {title#}</example> endif::backend-docbook[] +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] +<refentry> +<refmeta> +<refentrytitle>{mantitle}</refentrytitle> +<manvolnum>{manvolnum}</manvolnum> +<refmiscinfo class="source">Git</refmiscinfo> +<refmiscinfo class="version">@@GIT_VERSION@@</refmiscinfo> +<refmiscinfo class="manual">Git Manual</refmiscinfo> +</refmeta> +<refnamediv> + <refname>{manname}</refname> + <refpurpose>{manpurpose}</refpurpose> +</refnamediv> +endif::backend-docbook[] +endif::doctype-manpage[] + ifdef::backend-xhtml11[] [gitlink-inlinemacro] <a href="{target}.html">{target}{0?({0})}</a> diff --git a/Documentation/config.txt b/Documentation/config.txt index 7e41ca6a0d..2c0a666323 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -423,8 +423,34 @@ gitcvs.allbinary:: causes the client to treat all files as binary files which suppresses any newline munging it otherwise might do. A work-around for the fact that there is no way yet to set single files to mode '-kb'. + +gitcvs.dbname:: + Database used by git-cvsserver to cache revision information + derived from the git repository. The exact meaning depends on the + used database driver, for SQLite (which is the default driver) this + is a filename. Supports variable substitution (see + gitlink:git-cvsserver[1] for details). May not contain semicolons (`;`). + Default: '%Ggitcvs.%m.sqlite' + +gitcvs.dbdriver:: + Used Perl DBI driver. You can specify any available driver + for this here, but it might not work. git-cvsserver is tested + with 'DBD::SQLite', reported to work with 'DBD::Pg', and + reported *not* to work with 'DBD::mysql'. Experimental feature. + May not contain double colons (`:`). Default: 'SQLite'. See gitlink:git-cvsserver[1]. +gitcvs.dbuser, gitcvs.dbpass:: + Database user and password. Only useful if setting 'gitcvs.dbdriver', + since SQLite has no concept of database users and/or passwords. + 'gitcvs.dbuser' supports variable substitution (see + gitlink:git-cvsserver[1] for details). + +All gitcvs variables except for 'gitcvs.allbinary' can also specifed +as 'gitcvs.<access_method>.<varname>' (where 'access_method' is one +of "ext" and "pserver") to make them apply only for the given access +method. + http.sslVerify:: Whether to verify the SSL certificate when fetching or pushing over HTTPS. Can be overridden by the 'GIT_SSL_NO_VERIFY' environment diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 493474b2ee..8d1041598e 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -30,7 +30,8 @@ OPTIONS ------- --format=<fmt>:: - Format of the resulting archive: 'tar', 'zip'... + Format of the resulting archive: 'tar', 'zip'... The default + is 'tar'. --list:: Show all available formats. diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index b2bc58d851..5f68ee1584 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -15,7 +15,7 @@ DESCRIPTION The command takes various subcommands, and different options depending on the subcommand: - git bisect start [<paths>...] + git bisect start [<bad> [<good>...]] [--] [<paths>...] git bisect bad <rev> git bisect good <rev> git bisect reset [<branch>] @@ -134,15 +134,26 @@ $ git reset --hard HEAD~3 # try 3 revs before what Then compile and test the one you chose to try. After that, tell bisect what the result was as usual. -Cutting down bisection by giving path parameter to bisect start -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Cutting down bisection by giving more parameters to bisect start +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can further cut down the number of trials if you know what part of the tree is involved in the problem you are tracking down, by giving paths parameters when you say `bisect start`, like this: ------------ -$ git bisect start arch/i386 include/asm-i386 +$ git bisect start -- arch/i386 include/asm-i386 +------------ + +If you know beforehand more than one good commits, you can narrow the +bisect space down without doing the whole tree checkout every time you +give good commits. You give the bad revision immediately after `start` +and then you give all the good revisions you have: + +------------ +$ git bisect start v2.6.20-rc6 v2.6.20-rc4 v2.6.20-rc1 -- + # v2.6.20-rc6 is bad + # v2.6.20-rc4 and v2.6.20-rc1 are good ------------ Bisect run diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index f9e0c77379..d22844ba49 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -31,6 +31,10 @@ over pserver for anonymous CVS access. CVS clients cannot tag, branch or perform GIT merges. +git-cvsserver maps GIT branches to CVS modules. This is very different +from what most CVS users would expect since in CVS modules usually represent +one or more directories. + INSTALLATION ------------ @@ -65,9 +69,22 @@ env variable, you can rename git-cvsserver to cvs. ------ Note: you need to ensure each user that is going to invoke git-cvsserver has -write access to the log file and to the git repository. When offering anon -access via pserver, this means that the nobody user should have write access -to at least the sqlite database at the root of the repository. +write access to the log file and to the database (see +<<dbbackend,Database Backend>>. If you want to offer write access over +SSH, the users of course also need write access to the git repository itself. + +[[configaccessmethod]] +All configuration variables can also be overriden for a specific method of +access. Valid method names are "ext" (for SSH access) and "pserver". The +following example configuration would disable pserver access while still +allowing access over SSH. +------ + [gitcvs] + enabled=0 + + [gitcvs "ext"] + enabled=1 +------ -- 3. On the client machine you need to set the following variables. CVSROOT should be set as per normal, but the directory should point at the @@ -93,6 +110,90 @@ Example: cvs co -d project-master master ------ +[[dbbackend]] +Database Backend +---------------- + +git-cvsserver uses one database per git head (i.e. CVS module) to +store information about the repository for faster access. The +database doesn't contain any persitent data and can be completly +regenerated from the git repository at any time. The database +needs to be updated (i.e. written to) after every commit. + +If the commit is done directly by using git (as opposed to +using git-cvsserver) the update will need to happen on the +next repository access by git-cvsserver, independent of +access method and requested operation. + +That means that even if you offer only read access (e.g. by using +the pserver method), git-cvsserver should have write access to +the database to work reliably (otherwise you need to make sure +that the database if up-to-date all the time git-cvsserver is run). + +By default it uses SQLite databases in the git directory, named +`gitcvs.<module_name>.sqlite`. Note that the SQLite backend creates +temporary files in the same directory as the database file on +write so it might not be enough to grant the users using +git-cvsserver write access to the database file without granting +them write access to the directory, too. + +You can configure the database backend with the following +configuration variables: + +Configuring database backend +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +git-cvsserver uses the Perl DBI module. Please also read +its documentation if changing these variables, especially +about `DBI->connect()`. + +gitcvs.dbname:: + Database name. The exact meaning depends on the + used database driver, for SQLite this is a filename. + Supports variable substitution (see below). May + not contain semicolons (`;`). + Default: '%Ggitcvs.%m.sqlite' + +gitcvs.dbdriver:: + Used DBI driver. You can specify any available driver + for this here, but it might not work. cvsserver is tested + with 'DBD::SQLite', reported to work with + 'DBD::Pg', and reported *not* to work with 'DBD::mysql'. + Please regard this as an experimental feature. May not + contain double colons (`:`). + Default: 'SQLite' + +gitcvs.dbuser:: + Database user. Only useful if setting `dbdriver`, since + SQLite has no concept of database users. Supports variable + substitution (see below). + +gitcvs.dbpass:: + Database password. Only useful if setting `dbdriver`, since + SQLite has no concept of database passwords. + +All variables can also be set per access method, see <<configaccessmethod,above>>. + +Variable substitution +^^^^^^^^^^^^^^^^^^^^^ +In `dbdriver` and `dbuser` you can use the following variables: + +%G:: + git directory name +%g:: + git directory name, where all characters except for + alpha-numeric ones, `.`, and `-` are replaced with + `_` (this should make it easier to use the directory + name in a filename if wanted) +%m:: + CVS module/git head name +%a:: + access method (one of "ext" or "pserver") +%u:: + Name of the user running git-cvsserver. + If no name can be determined, the + numeric uid is used. + Eclipse CVS Client Notes ------------------------ diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 111d7c60bf..a33d157b97 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -10,11 +10,12 @@ SYNOPSIS -------- [verse] 'git-format-patch' [-n | -k] [-o <dir> | --stdout] [--thread] - [--attach[=<boundary>] | --inline[=<boundary>]] - [-s | --signoff] [<common diff options>] [--start-number <n>] - [--in-reply-to=Message-Id] [--suffix=.<sfx>] - [--ignore-if-in-upstream] - <since>[..<until>] + [--attach[=<boundary>] | --inline[=<boundary>]] + [-s | --signoff] [<common diff options>] [--start-number <n>] + [--in-reply-to=Message-Id] [--suffix=.<sfx>] + [--ignore-if-in-upstream] + [--subject-prefix=Subject-Prefix] + <since>[..<until>] DESCRIPTION ----------- @@ -98,6 +99,12 @@ include::diff-options.txt[] patches being generated, and any patch that matches is ignored. +--subject-prefix=<Subject-Prefix>:: + Instead of the standard '[PATCH]' prefix in the subject + line, instead use '[<Subject-Prefix>]'. This + allows for useful naming of a patch series, and can be + combined with the --numbered option. + --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specifed suffix. A common alternative is diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index 058009d2fa..8c68cf0372 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -9,7 +9,7 @@ git-fsck - Verifies the connectivity and validity of the objects in the database SYNOPSIS -------- [verse] -'git-fsck' [--tags] [--root] [--unreachable] [--cache] +'git-fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--full] [--strict] [<object>*] DESCRIPTION @@ -38,6 +38,12 @@ index file and all SHA1 references in .git/refs/* as heads. Consider any object recorded in the index also as a head node for an unreachability trace. +--no-reflogs:: + Do not consider commits that are referenced only by an + entry in a reflog to be reachable. This option is meant + only to search for commits that used to be in a ref, but + now aren't, but are still in that corresponding reflog. + --full:: Check not just objects in GIT_OBJECT_DIRECTORY ($GIT_DIR/objects), but also the ones found in alternate diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 0ff2890c7f..019c8bef7a 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -8,7 +8,7 @@ git-read-tree - Reads tree information into the index SYNOPSIS -------- -'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) +'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] [--index-output=<file>] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION @@ -86,6 +86,18 @@ OPTIONS file (usually '.gitignore') and allows such an untracked but explicitly ignored file to be overwritten. +--index-output=<file>:: + Instead of writing the results out to `$GIT_INDEX_FILE`, + write the resulting index in the named file. While the + command is operating, the original index file is locked + with the same mechanism as usual. The file must allow + to be rename(2)ed into from a temporary file that is + created next to the usual index file; typically this + means it needs to be on the same filesystem as the index + file itself, and you need write permission to the + directories the index file and index output file are + located in. + <tree-ish#>:: The id of the tree object(s) to be read/merged. diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index 11ce395c98..77e068b15f 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -22,11 +22,13 @@ SYNOPSIS [ \--topo-order ] [ \--parents ] [ \--left-right ] + [ \--cherry-pick ] [ \--encoding[=<encoding>] ] [ \--(author|committer|grep)=<pattern> ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] [ \--bisect ] + [ \--bisect-vars ] [ \--merge ] [ \--reverse ] [ \--walk-reflogs ] @@ -223,6 +225,20 @@ limiting may be applied. In addition to the '<commit>' listed on the command line, read them from the standard input. +--cherry-pick:: + + Omit any commit that introduces the same change as + another commit on the "other side" when the set of + commits are limited with symmetric difference. ++ +For example, if you have two branches, `A` and `B`, a usual way +to list all commits on only one side of them is with +`--left-right`, like the example above in the description of +that option. It however shows the commits that were cherry-picked +from the other branch (for example, "3rd on b" may be cherry-picked +from branch A). With this option, such pairs of commits are +excluded from the output. + -g, --walk-reflogs:: Instead of walking the commit ancestry chain, walk @@ -280,6 +296,18 @@ introduces a regression is thus reduced to a binary search: repeatedly generate and test new 'midpoint's until the commit chain is of length one. +--bisect-vars:: + +This calculates the same as `--bisect`, but outputs text ready +to be eval'ed by the shell. These lines will assign the name of +the midpoint revision to the variable `bisect_rev`, and the +expected number of commits to be tested after `bisect_rev` is +tested to `bisect_nr`, the expected number of commits to be +tested if `bisect_rev` turns out to be good to `bisect_good`, +the expected number of commits to be tested if `bisect_rev` +turns out to be bad to `bisect_bad`, and the number of commits +we are bisecting right now to `bisect_all`. + -- Commit Ordering diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 6feebc0400..a65f24a0f6 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -7,7 +7,7 @@ git-rm - Remove files from the working tree and from the index SYNOPSIS -------- -'git-rm' [-f] [-n] [-r] [--cached] [--] <file>... +'git-rm' [-f] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>... DESCRIPTION ----------- @@ -47,6 +47,13 @@ OPTIONS the paths only from the index, leaving working tree files. +\--ignore-unmatch:: + Exit with a zero status even if no files matched. + +\--quiet:: + git-rm normally outputs one line (in the form of an "rm" command) + for each file removed. This option suppresses that output. + DISCUSSION ---------- diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 2fe6c31967..d7ffc21ddf 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -117,6 +117,7 @@ The placeholders are: - '%Cgreen': switch color to green - '%Cblue': switch color to blue - '%Creset': reset color +- '%m': left, right or boundary mark - '%n': newline |