diff options
Diffstat (limited to 'Documentation')
27 files changed, 937 insertions, 38 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index ad87736b0c..3f92783d55 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -2,9 +2,10 @@ MAN1_TXT= \ $(filter-out $(addsuffix .txt, $(ARTICLES) $(SP_ARTICLES)), \ $(wildcard git-*.txt)) \ gitk.txt +MAN5_TXT=gitattributes.txt MAN7_TXT=git.txt -DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN7_TXT)) +DOC_HTML=$(patsubst %.txt,%.html,$(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)) ARTICLES = tutorial ARTICLES += tutorial-2 @@ -23,12 +24,14 @@ SP_ARTICLES = howto/revert-branch-rebase user-manual DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES)) DOC_MAN1=$(patsubst %.txt,%.1,$(MAN1_TXT)) +DOC_MAN5=$(patsubst %.txt,%.5,$(MAN5_TXT)) DOC_MAN7=$(patsubst %.txt,%.7,$(MAN7_TXT)) prefix?=$(HOME) bindir?=$(prefix)/bin mandir?=$(prefix)/man man1dir=$(mandir)/man1 +man5dir=$(mandir)/man5 man7dir=$(mandir)/man7 # DESTDIR= @@ -53,18 +56,27 @@ all: html man html: $(DOC_HTML) -$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN7): asciidoc.conf +$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7): asciidoc.conf -man: man1 man7 +man: man1 man5 man7 man1: $(DOC_MAN1) +man5: $(DOC_MAN5) man7: $(DOC_MAN7) install: man - $(INSTALL) -d -m755 $(DESTDIR)$(man1dir) $(DESTDIR)$(man7dir) + $(INSTALL) -d -m755 $(DESTDIR)$(man1dir) + $(INSTALL) -d -m755 $(DESTDIR)$(man5dir) + $(INSTALL) -d -m755 $(DESTDIR)$(man7dir) $(INSTALL) -m644 $(DOC_MAN1) $(DESTDIR)$(man1dir) + $(INSTALL) -m644 $(DOC_MAN5) $(DESTDIR)$(man5dir) $(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 +106,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 *.5 *.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 +%.1 %.5 %.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 +155,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..02b8ea0a68 --- /dev/null +++ b/Documentation/RelNotes-1.5.2.txt @@ -0,0 +1,176 @@ +GIT v1.5.2 Release Notes (draft) +======================== + +Updates since v1.5.1 +-------------------- + +* Plumbing level subproject support. + + You can include a subdirectory that has an independent git + repository in your index and tree objects as a + "subproject". This plumbing (i.e. "core") level subproject + support explicitly excludes recursive behaviour. + + The "subproject" entries in the index and trees are + incompatible with older versions of git. Experimenting with + the plumbing level support is encouraged, but be warned that + unless everybody in your project updates to this release or + later, using this feature would make your project + inaccessible by people with older versions of git. + +* Plumbing level gitattributes support. + + The gitattributes mechanism allows you to add 'attributes' to + paths in your project, and affect the way certain git + operations work. Currently you can influence if a path is + considered a binary or text (the former would be treated by + 'git diff' not to produce textual output; the latter can go + through the line endings conversion process in repositories + with core.autocrlf set), expand and unexpand '$ident$' keyword + with blob object name, specify a custom 3-way merge driver, + and specify a custom diff driver. You can also apply + arbitrary filter to contents on check-in/check-out codepath + but this feature is an extremely sharp-edged razor and needs + to be handled with caution (do not use it unless you + understand the earlier mailing list discussion on keyward + expansion). + +* The packfile format now optionally suports 64-bit index. + + This release supports the "version 2" format of the .idx + file. This is automatically enabled when a huge packfile + needs more than 32-bit to express offsets of objects in the + pack + +* 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]". + + - "git add -u" is a quick way to do the first stage of "git + commit -a" (i.e. update the index to match the working + tree); it obviously does not make a commit. + + - "git clean" honors a new configuration, "clean.requireforce". When + set to true, this makes "git clean" a no-op, preventing you + from losing files by typing "git clean" when you meant to + say "make clean". You can still say "git clean -f" to + override this. + + - "git log" family of commands learned --date={local,relative,default} + option. --date=relative is synonym to the --relative-date. + --date=local gives the timestamp in local timezone. + +* Updated behavior of existing commands. + + - When $GIT_COMMITTER_EMAIL or $GIT_AUTHOR_EMAIL is not set + but $EMAIL is set, the latter is used as a substitute. + + - "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". + + - "git cvsserver" can use backends other than sqlite. + + - "gitview" (in contrib/ section) learned to better support + "git-annotate". + + - "git diff $commit1:$path2 $commit2:$path2" can now report + mode changes between the two blobs. + + - Local "git fetch" from a repository whose object store is + one of the alternates (e.g. fetching from the origin in a + repository created with "git clone -l -s") avoids + downloading objects unnecessary. + + - "git blame" uses .mailmap to canonicalize the author name + just like "git shortlog" does. + +* 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. + + - The recursive merge strategy updated a worktree file that + was changed identically in two branches, when one of them + renamed it. We do not do that when there is no rename, so + match that behaviour. + +Fixes since v1.5.1 +------------------ + +All of the fixes in v1.5.1 maintenance series are included in +this release, unless otherwise noted. + +* Bugfixes + + - 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. + + - git-fetch had trouble with a remote with insanely large number + of refs. + +* Documentation updates + +* Performance Tweaks + +-- +exec >/var/tmp/1 +O=v1.5.2-rc1-32-g125a5f1 +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 8cf5093dd9..6a4da2ddd9 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -30,6 +30,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/cmd-list.perl b/Documentation/cmd-list.perl index 0381590d38..443802a9a3 100755 --- a/Documentation/cmd-list.perl +++ b/Documentation/cmd-list.perl @@ -84,6 +84,7 @@ git-bundle mainporcelain git-cat-file plumbinginterrogators git-checkout-index plumbingmanipulators git-checkout mainporcelain +git-check-attr purehelpers git-check-ref-format purehelpers git-cherry ancillaryinterrogators git-cherry-pick mainporcelain diff --git a/Documentation/config.txt b/Documentation/config.txt index a7daa08731..24f9655fef 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -300,6 +300,10 @@ branch.<name>.merge:: branch.<name>.merge to the desired branch, and use the special setting `.` (a period) for branch.<name>.remote. +clean.requireForce:: + A boolean to make git-clean do nothing unless given -f or -n. Defaults + to false. + color.branch:: A boolean to enable/disable color in the output of gitlink:git-branch[1]. May be set to `true` (or `always`), @@ -423,8 +427,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 @@ -499,6 +529,19 @@ merge.verbosity:: conflicts, 2 outputs conflicts and file changes. Level 5 and above outputs debugging information. The default is level 2. +merge.<driver>.name:: + Defines a human readable name for a custom low-level + merge driver. See gitlink:gitattributes[5] for details. + +merge.<driver>.driver:: + Defines the command that implements a custom low-level + merge driver. See gitlink:gitattributes[5] for details. + +merge.<driver>.recursive:: + Names a low-level merge driver to be used when + performing an internal merge between common ancestors. + See gitlink:gitattributes[5] for details. + pack.window:: The size of the window used by gitlink:git-pack-objects[1] when no window size is given on the command line. Defaults to 10. @@ -567,8 +610,8 @@ tar.umask:: user.email:: Your email address to be recorded in any newly created commits. - Can be overridden by the 'GIT_AUTHOR_EMAIL' and 'GIT_COMMITTER_EMAIL' - environment variables. See gitlink:git-commit-tree[1]. + Can be overridden by the 'GIT_AUTHOR_EMAIL', 'GIT_COMMITTER_EMAIL', and + 'EMAIL' environment variables. See gitlink:git-commit-tree[1]. user.name:: Your full name to be recorded in any newly created commits. diff --git a/Documentation/core-tutorial.txt b/Documentation/core-tutorial.txt index 97cdb90cb4..6b9b9ad7d1 100644 --- a/Documentation/core-tutorial.txt +++ b/Documentation/core-tutorial.txt @@ -319,10 +319,9 @@ argument to `git-commit-tree`. `git-commit-tree` normally takes several arguments -- it wants to know what the 'parent' of a commit was, but since this is the first commit ever in this new repository, and it has no parents, we only need to pass in -the object name of the tree. However, `git-commit-tree` -also wants to get a commit message -on its standard input, and it will write out the resulting object name for the -commit to its standard output. +the object name of the tree. However, `git-commit-tree` also wants to get a +commit message on its standard input, and it will write out the resulting +object name for the commit to its standard output. And this is where we create the `.git/refs/heads/master` file which is pointed at by `HEAD`. This file is supposed to contain @@ -1304,7 +1303,7 @@ So, we can use somebody else's work from a remote repository, but how can *you* prepare a repository to let other people pull from it? -Your do your real work in your working tree that has your +You do your real work in your working tree that has your primary repository hanging under it as its `.git` subdirectory. You *could* make that repository accessible remotely and ask people to pull from it, but in practice that is not the way diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 755d7186f5..ea2701846f 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -7,7 +7,7 @@ git-add - Add file contents to the changeset to be committed next SYNOPSIS -------- -'git-add' [-n] [-v] [-f] [--interactive | -i] [--] <file>... +'git-add' [-n] [-v] [-f] [--interactive | -i] [-u] [--] <file>... DESCRIPTION ----------- @@ -56,6 +56,10 @@ OPTIONS Add modified contents in the working tree interactively to the index. +-u:: + Update all files that git already knows about. This is what + "git commit -a" does in preparation for making a commit. + \--:: This option can be used to separate command-line options from the list of files, (useful when filenames might be mistaken diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 59dfabed23..d3ca9a90ce 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, -l:: 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-blame.txt b/Documentation/git-blame.txt index 8f9439a6dd..44678b0c36 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -8,7 +8,7 @@ git-blame - Show what revision and author last modified each line of a file SYNOPSIS -------- [verse] -'git-blame' [-c] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] +'git-blame' [-c] [-b] [--root] [-s] [-l] [-t] [-f] [-n] [-p] [--incremental] [-L n,m] [-S <revs-file>] [-M] [-C] [-C] [--since=<date>] [<rev> | --contents <file>] [--] <file> @@ -60,6 +60,9 @@ include::blame-options.txt[] -n, --show-number:: Show line number in the original commit (Default: off). +-s:: + Suppress author name and timestamp from the output. + THE PORCELAIN FORMAT -------------------- diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt new file mode 100644 index 0000000000..ceb51959b1 --- /dev/null +++ b/Documentation/git-check-attr.txt @@ -0,0 +1,37 @@ +git-check-attr(1) +================= + +NAME +---- +git-check-attr - Display gitattributes information. + + +SYNOPSIS +-------- +'git-check-attr' attr... [--] pathname... + +DESCRIPTION +----------- +For every pathname, this command will list if each attr is 'unspecified', +'set', or 'unset' as a gitattribute on that pathname. + +OPTIONS +------- +\--:: + Interpret all preceding arguments as attributes, and all following + arguments as path names. If not supplied, only the first argument will + be treated as an attribute. + + +Author +------ +Written by Junio C Hamano <junkio@cox.net> + +Documentation +-------------- +Documentation by James Bowes. + +GIT +--- +Part of the gitlink:git[7] suite + diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index c61afbcdba..5aff026eb4 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git-clean' [-d] [-n] [-q] [-x | -X] [--] <paths>... +'git-clean' [-d] [-f] [-n] [-q] [-x | -X] [--] <paths>... DESCRIPTION ----------- @@ -25,6 +25,10 @@ OPTIONS -d:: Remove untracked directories in addition to untracked files. +-f:: + If the git configuration specifies clean.forceRequire as true, + git-clean will refuse to run unless given -f or -n. + -n:: Don't actually remove anything, just show what would be done. diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 1571dbbb74..504a3aa1b4 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -61,6 +61,7 @@ either `.git/config` file, or using the following environment variables. GIT_COMMITTER_NAME GIT_COMMITTER_EMAIL GIT_COMMITTER_DATE + EMAIL (nb "<", ">" and "\n"s are stripped) 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-index-pack.txt b/Documentation/git-index-pack.txt index 2229ee86b7..b7a49b9f58 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -68,6 +68,11 @@ OPTIONS message can later be searched for within all .keep files to locate any which have outlived their usefulness. +--index-version=<version>[,<offset>]:: + This is intended to be used by the test suite only. It allows + to force the version for the generated pack index, and to force + 64-bit index entries on objects located above the given offset. + Note ---- diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index fdc6f97289..d9e11c6534 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -138,6 +138,11 @@ base-name:: length, this option typically shrinks the resulting packfile by 3-5 per-cent. +--index-version=<version>[,<offset>]:: + This is intended to be used by the test suite only. It allows + to force the version for the generated pack index, and to force + 64-bit index entries on objects located above the given offset. + Author ------ 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..1b12b4f2a4 100644 --- a/Documentation/git-rev-list.txt +++ b/Documentation/git-rev-list.txt @@ -22,11 +22,14 @@ SYNOPSIS [ \--topo-order ] [ \--parents ] [ \--left-right ] + [ \--cherry-pick ] [ \--encoding[=<encoding>] ] [ \--(author|committer|grep)=<pattern> ] + [ \--date={local|relative|default} ] [ [\--objects | \--objects-edge] [ \--unpacked ] ] [ \--pretty | \--header ] [ \--bisect ] + [ \--bisect-vars ] [ \--merge ] [ \--reverse ] [ \--walk-reflogs ] @@ -88,9 +91,20 @@ include::pretty-formats.txt[] --relative-date:: - Show dates relative to the current time, e.g. "2 hours ago". + Synonym for `--date=relative`. + +--date={relative,local,default}:: + Only takes effect for dates shown in human-readable format, such as when using "--pretty". ++ +`--date=relative` shows dates relative to the current time, +e.g. "2 hours ago". ++ +`--date=local` shows timestamps in user's local timezone. ++ +`--date=default` shows timestamps in the original timezone +(either committer's or author's). --header:: @@ -223,6 +237,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 +308,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/git-tag.txt b/Documentation/git-tag.txt index 70235e8ddb..4e3e02756c 100644 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@ -9,9 +9,10 @@ git-tag - Create, list, delete or verify a tag object signed with GPG SYNOPSIS -------- [verse] -'git-tag' [-a | -s | -u <key-id>] [-f | -v] [-m <msg> | -F <file>] <name> [<head>] +'git-tag' [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] <name> [<head>] 'git-tag' -d <name>... 'git-tag' -l [<pattern>] +'git-tag' -v <name> DESCRIPTION ----------- @@ -77,8 +78,10 @@ committer identity (of the form "Your Name <your@email.address>") to find a key. If you want to use a different default key, you can specify it in the repository configuration as follows: +------------------------------------- [user] signingkey = <gpg-key-id> +------------------------------------- DISCUSSION diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index cd5e014d48..6cfbd9a842 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -27,6 +27,9 @@ Modifies the index or directory cache. Each file mentioned is updated into the index and any 'unmerged' or 'needs updating' state is cleared. +See also gitlink:git-add[1] for a more user-friendly way to do some of +the most common operations on the index. + The way "git-update-index" handles files it is told about can be modified using the various options: @@ -306,7 +309,8 @@ The command looks at `core.ignorestat` configuration variable. See See Also -------- -gitlink:git-config[1] +gitlink:git-config[1], +gitlink:git-add[1] Author diff --git a/Documentation/git.txt b/Documentation/git.txt index c2b7f3fec6..f84728bc11 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -40,7 +40,11 @@ Documentation for older releases are available here: * link:RelNotes-1.5.1.txt[release notes for 1.5.1] -* link:v1.5.0.7/git.html[documentation for release 1.5.0.7] +* link:v1.5.1.2/git.html[documentation for release 1.5.1.2] + +* link:RelNotes-1.5.1.2.txt[release notes for 1.5.1.2] + +* link:RelNotes-1.5.1.1.txt[release notes for 1.5.1.1] * link:RelNotes-1.5.0.7.txt[release notes for 1.5.0.7] @@ -344,6 +348,7 @@ git Commits 'GIT_COMMITTER_NAME':: 'GIT_COMMITTER_EMAIL':: 'GIT_COMMITTER_DATE':: +'EMAIL':: see gitlink:git-commit-tree[1] git Diffs diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt new file mode 100644 index 0000000000..87723105d1 --- /dev/null +++ b/Documentation/gitattributes.txt @@ -0,0 +1,379 @@ +gitattributes(5) +================ + +NAME +---- +gitattributes - defining attributes per path + +SYNOPSIS +-------- +$GIT_DIR/info/attributes, gitattributes + + +DESCRIPTION +----------- + +A `gitattributes` file is a simple text file that gives +`attributes` to pathnames. + +Each line in `gitattributes` file is of form: + + glob attr1 attr2 ... + +That is, a glob pattern followed by an attributes list, +separated by whitespaces. When the glob pattern matches the +path in question, the attributes listed on the line are given to +the path. + +Each attribute can be in one of these states for a given path: + +Set:: + + The path has the attribute with special value "true"; + this is specified by listing only the name of the + attribute in the attribute list. + +Unset:: + + The path has the attribute with special value "false"; + this is specified by listing the name of the attribute + prefixed with a dash `-` in the attribute list. + +Set to a value:: + + The path has the attribute with specified string value; + this is specified by listing the name of the attribute + followed by an equal sign `=` and its value in the + attribute list. + +Unspecified:: + + No glob pattern matches the path, and nothing says if + the path has or does not have the attribute, the + attribute for the path is said to be Unspecified. + +When more than one glob pattern matches the path, a later line +overrides an earlier line. This overriding is done per +attribute. + +When deciding what attributes are assigned to a path, git +consults `$GIT_DIR/info/attributes` file (which has the highest +precedence), `.gitattributes` file in the same directory as the +path in question, and its parent directories (the further the +directory that contains `.gitattributes` is from the path in +question, the lower its precedence). + +Sometimes you would need to override an setting of an attribute +for a path to `unspecified` state. This can be done by listing +the name of the attribute prefixed with an exclamation point `!`. + + +EFFECTS +------- + +Certain operations by git can be influenced by assigning +particular attributes to a path. Currently, three operations +are attributes-aware. + +Checking-out and checking-in +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These attributes affect how the contents stored in the +repository are copied to the working tree files when commands +such as `git checkout` and `git merge` run. They also affect how +git stores the contents you prepare in the working tree in the +repository upon `git add` and `git commit`. + +`crlf` +^^^^^^ + +This attribute controls the line-ending convention. + +Set:: + + Setting the `crlf` attribute on a path is meant to mark + the path as a "text" file. 'core.autocrlf' conversion + takes place without guessing the content type by + inspection. + +Unset:: + + Unsetting the `crlf` attribute on a path is meant to + mark the path as a "binary" file. The path never goes + through line endings conversion upon checkin/checkout. + +Unspecified:: + + Unspecified `crlf` attribute tells git to apply the + `core.autocrlf` conversion when the file content looks + like text. + +Set to string value "input":: + + This is similar to setting the attribute to `true`, but + also forces git to act as if `core.autocrlf` is set to + `input` for the path. + +Any other value set to `crlf` attribute is ignored and git acts +as if the attribute is left unspecified. + + +The `core.autocrlf` conversion +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If the configuration variable `core.autocrlf` is false, no +conversion is done. + +When `core.autocrlf` is true, it means that the platform wants +CRLF line endings for files in the working tree, and you want to +convert them back to the normal LF line endings when checking +in to the repository. + +When `core.autocrlf` is set to "input", line endings are +converted to LF upon checkin, but there is no conversion done +upon checkout. + + +`ident` +^^^^^^^ + +When the attribute `ident` is set to a path, git replaces +`$ident$` in the blob object with `$ident:`, followed by +40-character hexadecimal blob object name, followed by a dollar +sign `$` upon checkout. Any byte sequence that begins with +`$ident:` and ends with `$` in the worktree file is replaced +with `$ident$` upon check-in. + + +Interaction between checkin/checkout attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the check-in codepath, the worktree file is first converted +with `ident` (if specified), and then with `crlf` (again, if +specified and applicable). + +In the check-out codepath, the blob content is first converted +with `crlf`, and then `ident`. + + +`filter` +^^^^^^^^ + +A `filter` attribute can be set to a string value. This names +filter driver specified in the configuration. + +A filter driver consists of `clean` command and `smudge` +command, either of which can be left unspecified. Upon +checkout, when `smudge` command is specified, the command is fed +the blob object from its standard input, and its standard output +is used to update the worktree file. Similarly, `clean` command +is used to convert the contents of worktree file upon checkin. + +Missing filter driver definition in the config is not an error +but makes the filter a no-op passthru. + +The content filtering is done to massage the content into a +shape that is more convenient for the platform, filesystem, and +the user to use. The keyword here is "more convenient" and not +"turning something unusable into usable". In other words, it is +"hanging yourself because we gave you a long rope" if your +project uses filtering mechanism in such a way that it makes +your project unusable unless the checkout is done with a +specific filter in effect. + + +Interaction between checkin/checkout attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the check-in codepath, the worktree file is first converted +with `filter` driver (if specified and corresponding driver +defined), then the result is processed with `ident` (if +specified), and then finally with `crlf` (again, if specified +and applicable). + +In the check-out codepath, the blob content is first converted +with `crlf`, and then `ident` and fed to `filter`. + + +Generating diff text +~~~~~~~~~~~~~~~~~~~~ + +The attribute `diff` affects if `git diff` generates textual +patch for the path or just says `Binary files differ`. + +Set:: + + A path to which the `diff` attribute is set is treated + as text, even when they contain byte values that + normally never appear in text files, such as NUL. + +Unset:: + + A path to which the `diff` attribute is unset will + generate `Binary files differ`. + +Unspecified:: + + A path to which the `diff` attribute is unspecified + first gets its contents inspected, and if it looks like + text, it is treated as text. Otherwise it would + generate `Binary files differ`. + +String:: + + Diff is shown using the specified custom diff driver. + The driver program is given its input using the same + calling convention as used for GIT_EXTERNAL_DIFF + program. + + +Defining a custom diff driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The definition of a diff driver is done in `gitconfig`, not +`gitattributes` file, so strictly speaking this manual page is a +wrong place to talk about it. However... + +To define a custom diff driver `jcdiff`, add a section to your +`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: + +---------------------------------------------------------------- +[diff "jcdiff"] + command = j-c-diff +---------------------------------------------------------------- + +When git needs to show you a diff for the path with `diff` +attribute set to `jcdiff`, it calls the command you specified +with the above configuration, i.e. `j-c-diff`, with 7 +parameters, just like `GIT_EXTERNAL_DIFF` program is called. +See gitlink:git[7] for details. + + +Performing a three-way merge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The attribute `merge` affects how three versions of a file is +merged when a file-level merge is necessary during `git merge`, +and other programs such as `git revert` and `git cherry-pick`. + +Set:: + + Built-in 3-way merge driver is used to merge the + contents in a way similar to `merge` command of `RCS` + suite. This is suitable for ordinary text files. + +Unset:: + + Take the version from the current branch as the + tentative merge result, and declare that the merge has + conflicts. This is suitable for binary files that does + not have a well-defined merge semantics. + +Unspecified:: + + By default, this uses the same built-in 3-way merge + driver as is the case the `merge` attribute is set. + However, `merge.default` configuration variable can name + different merge driver to be used for paths to which the + `merge` attribute is unspecified. + +String:: + + 3-way merge is performed using the specified custom + merge driver. The built-in 3-way merge driver can be + explicitly specified by asking for "text" driver; the + built-in "take the current branch" driver can be + requested with "binary". + + +Defining a custom merge driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The definition of a merge driver is done in `gitconfig` not +`gitattributes` file, so strictly speaking this manual page is a +wrong place to talk about it. However... + +To define a custom merge driver `filfre`, add a section to your +`$GIT_DIR/config` file (or `$HOME/.gitconfig` file) like this: + +---------------------------------------------------------------- +[merge "filfre"] + name = feel-free merge driver + driver = filfre %O %A %B + recursive = binary +---------------------------------------------------------------- + +The `merge.*.name` variable gives the driver a human-readable +name. + +The `merge.*.driver` variable's value is used to construct a +command to run to merge ancestor's version (`%O`), current +version (`%A`) and the other branches' version (`%B`). These +three tokens are replaced with the names of temporary files that +hold the contents of these versions when the command line is +built. + +The merge driver is expected to leave the result of the merge in +the file named with `%A` by overwriting it, and exit with zero +status if it managed to merge them cleanly, or non-zero if there +were conflicts. + +The `merge.*.recursive` variable specifies what other merge +driver to use when the merge driver is called for an internal +merge between common ancestors, when there are more than one. +When left unspecified, the driver itself is used for both +internal merge and the final merge. + + +EXAMPLE +------- + +If you have these three `gitattributes` file: + +---------------------------------------------------------------- +(in $GIT_DIR/info/attributes) + +a* foo !bar -baz + +(in .gitattributes) +abc foo bar baz + +(in t/.gitattributes) +ab* merge=filfre +abc -foo -bar +*.c frotz +---------------------------------------------------------------- + +the attributes given to path `t/abc` are computed as follows: + +1. By examining `t/.gitattributes` (which is in the same + diretory as the path in question), git finds that the first + line matches. `merge` attribute is set. It also finds that + the second line matches, and attributes `foo` and `bar` + are unset. + +2. Then it examines `.gitattributes` (which is in the parent + directory), and finds that the first line matches, but + `t/.gitattributes` file already decided how `merge`, `foo` + and `bar` attributes should be given to this path, so it + leaves `foo` and `bar` unset. Attribute `baz` is set. + +3. Finally it examines `$GIT_DIR/info/gitattributes`. This file + is used to override the in-tree settings. The first line is + a match, and `foo` is set, `bar` is reverted to unspecified + state, and `baz` is unset. + +As the result, the attributes assignement to `t/abc` becomes: + +---------------------------------------------------------------- +foo set to true +bar unspecified +baz set to false +merge set to string value "filfre" +frotz unspecified +---------------------------------------------------------------- + + +GIT +--- +Part of the gitlink:git[7] suite 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 |