diff options
Diffstat (limited to 'Documentation')
35 files changed, 1078 insertions, 119 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index ad87736..3f92783 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 0000000..6195715 --- /dev/null +++ b/Documentation/RelNotes-1.5.2.txt @@ -0,0 +1,197 @@ +GIT v1.5.2 Release Notes +======================== + +Updates since v1.5.1 +-------------------- + +* Plumbing level superproject support. + + You can include a subdirectory that has an independent git + repository in your index and tree objects of your project + ("superproject"). This plumbing (i.e. "core") level + superproject support explicitly excludes recursive behaviour. + + The "subproject" entries in the index and trees of a superproject + 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 '$Id$' 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 keyword + expansion). These conversions apply when checking files in + or out, and exporting via git-archive. + +* 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. + +* Comes with an updated git-gui 0.7.1 + +* Updated gitweb: + + - can show combined diff for merges; + - uses font size of user's preference, not hardcoded in pixels; + - can now 'grep'; + +* 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 unnecessarily. + + - "git blame" uses .mailmap to canonicalize the author name + just like "git shortlog" does. + + - "git pack-objects" pays attention to pack.depth + configuration variable. + + - "git cherry-pick" and "git revert" does not use .msg file in + the working tree to prepare commit message; instead it uses + $GIT_DIR/MERGE_MSG as other commands do. + +* 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. + + - Optimized "git-diff-tree" for reduced memory footprint. + + - 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. This avoids excessive rebuilds. + + - The default pack depth has been increased to 50, as the + recent addition of delta_base_cache makes deeper delta chains + much less expensive to access. Depending on the project, it was + reported that this reduces the resulting pack file by 10% + or so. + + +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. + + - "git clean -d -X" now does not remove non-excluded directories. + + - rebasing (without -m) a series that changes a symlink to a directory + in the middle of a path confused git-apply greatly and refused to + operate. diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 1ba9041..b94d9a8 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 44b1ce4..fa7dc94 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 0381590..443802a 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 c3fc64a..4bbe116 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -305,6 +305,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`), @@ -428,8 +432,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 @@ -504,10 +534,27 @@ 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. +pack.depth:: + The maximum delta depth used by gitlink:git-pack-objects[1] when no + maximum depth is given on the command line. Defaults to 50. + pull.octopus:: The default merge strategy to use when pulling multiple branches at once. @@ -572,8 +619,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 97cdb90..6b9b9ad 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 38c72b8..a0c9f68 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,13 @@ OPTIONS Add modified contents in the working tree interactively to the index. +-u:: + Update only files that git already knows about. This is similar + to what "git commit -a" does in preparation for making a commit, + except that the update is limited to paths specified on the + command line. If no paths are specified, all tracked files are + updated. + \--:: 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 5fd3b62..721e035 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -31,7 +31,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 b2bc58d..5f68ee1 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 8f9439a..44678b0 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 0000000..ceb5195 --- /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 c61afbc..e3252d5 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.requireForce 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 1571dbb..504a3aa 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 f9e0c77..d22844b 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-diff-tree.txt b/Documentation/git-diff-tree.txt index 5d6e9dc..6e660e2 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -73,7 +73,7 @@ separated with a single space are given. This flag causes "git-diff-tree --stdin" to also show the commit message before the differences. -include::pretty-formats.txt[] +include::pretty-options.txt[] --no-commit-id:: git-diff-tree outputs a line with the commit ID when @@ -104,6 +104,9 @@ include::pretty-formats.txt[] if the diff itself is empty. +include::pretty-formats.txt[] + + Limiting Output --------------- If you're only interested in differences in a subset of files, for diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 111d7c6..a33d157 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 058009d..8c68cf0 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 c498bed..2269269 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -70,6 +70,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-log.txt b/Documentation/git-log.txt index 49bb539..0f353f6 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -25,7 +25,7 @@ This manual page describes only the most frequently used options. OPTIONS ------- -include::pretty-formats.txt[] +include::pretty-options.txt[] -<n>:: Limits the number of commits to show. @@ -51,10 +51,16 @@ include::pretty-formats.txt[] a record about how the tip of a reference was changed. See also gitlink:git-reflog[1]. +--decorate:: + Print out the ref names of any commits that are shown. + <paths>...:: Show only commits that affect the specified paths. +include::pretty-formats.txt[] + + Examples -------- git log --no-merges:: diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 79e0b7b..076cebc 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -42,8 +42,8 @@ OPTIONS Show other files in the output -i|--ignored:: - Show ignored files in the output - Note the this also reverses any exclude list present. + Show ignored files in the output. + Note that this also reverses any exclude list present. -s|--stage:: Show stage files in the output diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt index fdc6f97..bd3ee45 100644 --- a/Documentation/git-pack-objects.txt +++ b/Documentation/git-pack-objects.txt @@ -83,7 +83,7 @@ base-name:: it too deep affects the performance on the unpacker side, because delta data needs to be applied that many times to get to the necessary object. - The default value for both --window and --depth is 10. + The default value for --window is 10 and --depth is 50. --incremental:: This flag causes an object already in a pack ignored @@ -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 0ff2890..019c8be 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-repack.txt b/Documentation/git-repack.txt index d39abc1..cc3b0b2 100644 --- a/Documentation/git-repack.txt +++ b/Documentation/git-repack.txt @@ -63,7 +63,7 @@ OPTIONS space. `--depth` limits the maximum delta depth; making it too deep affects the performance on the unpacker side, because delta data needs to be applied that many times to get to the necessary object. - The default value for both --window and --depth is 10. + The default value for --window is 10 and --depth is 50. Configuration diff --git a/Documentation/git-rev-list.txt b/Documentation/git-rev-list.txt index fde9a72..c3c2043 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 ] @@ -84,13 +87,24 @@ Using these options, gitlink:git-rev-list[1] will act similar to the more specialized family of commit log tools: gitlink:git-log[1], gitlink:git-show[1], and gitlink:git-whatchanged[1] -include::pretty-formats.txt[] +include::pretty-options.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 @@ -327,6 +367,10 @@ These options are mostly targeted for packing of git repositories. Only useful with '--objects'; print the object IDs that are not in packs. + +include::pretty-formats.txt[] + + Author ------ Written by Linus Torvalds <torvalds@osdl.org> diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index 6feebc0..a65f24a 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-show.txt b/Documentation/git-show.txt index 5a219ab..34c5caf 100644 --- a/Documentation/git-show.txt +++ b/Documentation/git-show.txt @@ -38,6 +38,9 @@ OPTIONS For a more complete list of ways to spell object names, see "SPECIFYING REVISIONS" section in gitlink:git-rev-parse[1]. +include::pretty-options.txt[] + + include::pretty-formats.txt[] diff --git a/Documentation/git-tag.txt b/Documentation/git-tag.txt index 70235e8..4e3e027 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 cd5e014..6cfbd9a 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 c2b7f3fec..98860af 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -35,34 +35,43 @@ documentation can be viewed at ifdef::stalenotes[] [NOTE] ============ -You are reading the documentation for the latest version of git. -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:RelNotes-1.5.0.7.txt[release notes for 1.5.0.7] -* link:RelNotes-1.5.0.6.txt[release notes for 1.5.0.6] - -* link:RelNotes-1.5.0.5.txt[release notes for 1.5.0.5] - -* link:RelNotes-1.5.0.3.txt[release notes for 1.5.0.3] +You are reading the documentation for the latest (possibly +unreleased) version of git, that is available from 'master' +branch of the `git.git` repository. +Documentation for older releases are available here: -* link:RelNotes-1.5.0.2.txt[release notes for 1.5.0.2] +* link:v1.5.2/git.html[documentation for release 1.5.2] -* link:RelNotes-1.5.0.1.txt[release notes for 1.5.0.1] +* release notes for + link:RelNotes-1.5.2.txt[1.5.2]. -* link:RelNotes-1.5.0.txt[release notes for 1.5.0] +* link:v1.5.1.6/git.html[documentation for release 1.5.1.6] -* link:v1.4.4.4/git.html[documentation for release 1.4.4.4] +* release notes for + link:RelNotes-1.5.1.6.txt[1.5.1.6], + link:RelNotes-1.5.1.5.txt[1.5.1.5], + link:RelNotes-1.5.1.4.txt[1.5.1.4], + link:RelNotes-1.5.1.3.txt[1.5.1.3], + link:RelNotes-1.5.1.2.txt[1.5.1.2], + link:RelNotes-1.5.1.1.txt[1.5.1.1], + link:RelNotes-1.5.1.txt[1.5.1]. -* link:v1.3.3/git.html[documentation for release 1.3.3] +* link:v1.5.0.7/git.html[documentation for release 1.5.0.7] -* link:v1.2.6/git.html[documentation for release 1.2.6] +* release notes for + link:RelNotes-1.5.0.7.txt[1.5.0.7], + link:RelNotes-1.5.0.6.txt[1.5.0.6], + link:RelNotes-1.5.0.5.txt[1.5.0.5], + link:RelNotes-1.5.0.3.txt[1.5.0.3], + link:RelNotes-1.5.0.2.txt[1.5.0.2], + link:RelNotes-1.5.0.1.txt[1.5.0.1], + link:RelNotes-1.5.0.txt[1.5.0]. -* link:v1.0.13/git.html[documentation for release 1.0.13] +* documentation for release link:v1.4.4.4/git.html[1.4.4.4], + link:v1.3.3/git.html[1.3.3], + link:v1.2.6/git.html[1.2.6], + link:v1.0.13/git.html[1.0.13]. ============ @@ -344,6 +353,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 0000000..d3ac9c7 --- /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 +`$Id$` in the blob object with `$Id:`, followed by +40-character hexadecimal blob object name, followed by a dollar +sign `$` upon checkout. Any byte sequence that begins with +`$Id:` and ends with `$` in the worktree file is replaced +with `$Id$` 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/hooks.txt b/Documentation/hooks.txt index 80ba670..aabb975 100644 --- a/Documentation/hooks.txt +++ b/Documentation/hooks.txt @@ -115,8 +115,9 @@ If the hook exits with non-zero status, none of the refs will be updated. If the hook exits with zero, updating of individual refs can still be prevented by the <<update,'update'>> hook. -If you want to report something to the `git-send-pack` on the other end, -you can simply `echo` your messages. +Both standard output and standard error output are forwarded to +`git-send-pack` on the other end, so you can simply `echo` messages +for the user. [[update]] update @@ -153,9 +154,9 @@ Another use suggested on the mailing list is to use this hook to implement access control which is finer grained than the one based on filesystem group. -The standard output of this hook is sent to `stderr`, so if you -want to report something to the `git-send-pack` on the other end, -you can simply `echo` your messages. +Both standard output and standard error output are forwarded to +`git-send-pack` on the other end, so you can simply `echo` messages +for the user. The default 'update' hook, when enabled--and with `hooks.allowunannotated` config option turned on--prevents @@ -171,17 +172,20 @@ It executes on the remote repository once after all the refs have been updated. This hook executes once for the receive operation. It takes no -arguments, but gets the same information as the `pre-receive` +arguments, but gets the same information as the +<<pre-receive,'pre-receive'>> hook does on its standard input. This hook does not affect the outcome of `git-receive-pack`, as it is called after the real work is done. -This supersedes the [[post-update]] hook in that it actually get's -both old and new values of all the refs. +This supersedes the <<post-update,'post-update'>> hook in that it get's +both old and new values of all the refs in addition to their +names. -If you want to report something to the `git-send-pack` on the -other end, you can simply `echo` your messages. +Both standard output and standard error output are forwarded to +`git-send-pack` on the other end, so you can simply `echo` messages +for the user. The default 'post-receive' hook is empty, but there is a sample script `post-receive-email` provided in the `contrib/hooks` @@ -205,12 +209,10 @@ the outcome of `git-receive-pack`. The 'post-update' hook can tell what are the heads that were pushed, but it does not know what their original and updated values are, -so it is a poor place to do log old..new. - -In general, `post-receive` hook is preferred when the hook needs -to decide its acion on the status of the entire set of refs -being updated, as this hook is called once per ref, with -information only on a single ref at a time. +so it is a poor place to do log old..new. The +<<post-receive,'post-receive'>> hook does get both original and +updated values of the refs. You might consider it instead if you need +them. When enabled, the default 'post-update' hook runs `git-update-server-info` to keep the information used by dumb @@ -219,4 +221,5 @@ a git repository that is accessible via HTTP, you should probably enable this hook. Both standard output and standard error output are forwarded to -`git-send-pack` on the other end. +`git-send-pack` on the other end, so you can simply `echo` messages +for the user. diff --git a/Documentation/pretty-formats.txt b/Documentation/pretty-formats.txt index 2fe6c31..d922e8e 100644 --- a/Documentation/pretty-formats.txt +++ b/Documentation/pretty-formats.txt @@ -1,31 +1,32 @@ ---pretty[='<format>']:: - - Pretty-prints the details of a commit. `--pretty` - without an explicit `=<format>` defaults to 'medium'. - If the commit is a merge, and if the pretty-format - is not 'oneline', 'email' or 'raw', an additional line is - inserted before the 'Author:' line. This line begins with - "Merge: " and the sha1s of ancestral commits are printed, - separated by spaces. Note that the listed commits may not - necessarily be the list of the *direct* parent commits if you - have limited your view of history: for example, if you are - only interested in changes related to a certain directory or - file. Here are some additional details for each format: - - * 'oneline' +PRETTY FORMATS +-------------- + +If the commit is a merge, and if the pretty-format +is not 'oneline', 'email' or 'raw', an additional line is +inserted before the 'Author:' line. This line begins with +"Merge: " and the sha1s of ancestral commits are printed, +separated by spaces. Note that the listed commits may not +necessarily be the list of the *direct* parent commits if you +have limited your view of history: for example, if you are +only interested in changes related to a certain directory or +file. + +Here are some additional details for each format: + +* 'oneline' <sha1> <title line> + This is designed to be as compact as possible. - * 'short' +* 'short' commit <sha1> Author: <author> <title line> - * 'medium' +* 'medium' commit <sha1> Author: <author> @@ -35,7 +36,7 @@ This is designed to be as compact as possible. <full commit message> - * 'full' +* 'full' commit <sha1> Author: <author> @@ -45,7 +46,7 @@ This is designed to be as compact as possible. <full commit message> - * 'fuller' +* 'fuller' commit <sha1> Author: <author> @@ -57,18 +58,16 @@ This is designed to be as compact as possible. <full commit message> - - * 'email' +* 'email' From <sha1> <date> From: <author> Date: <date & time> Subject: [PATCH] <title line> - full commit message> - + <full commit message> - * 'raw' +* 'raw' + The 'raw' format shows the entire commit exactly as stored in the commit object. Notably, the SHA1s are @@ -77,19 +76,22 @@ displayed in full, regardless of whether --abbrev or true parent commits, without taking grafts nor history simplification into account. - * 'format:' +* 'format:' + The 'format:' format allows you to specify which information you want to show. It works a little bit like printf format, with the notable exception that you get a newline with '%n' instead of '\n'. - -E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<"' ++ +E.g, 'format:"The author of %h was %an, %ar%nThe title was >>%s<<%n"' would show something like this: - ++ +------- The author of fe6e0ee was Junio C Hamano, 23 hours ago The title was >>t4119: test autocomputing -p<n> for traditional diff input.<< +-------- ++ The placeholders are: - '%H': commit hash @@ -117,13 +119,6 @@ The placeholders are: - '%Cgreen': switch color to green - '%Cblue': switch color to blue - '%Creset': reset color +- '%m': left, right or boundary mark - '%n': newline - ---encoding[=<encoding>]:: - The commit objects record the encoding used for the log message - in their encoding header; this option can be used to tell the - command to re-code the commit log message in the encoding - preferred by the user. For non plumbing commands this - defaults to UTF-8. - diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt new file mode 100644 index 0000000..7d515be --- /dev/null +++ b/Documentation/pretty-options.txt @@ -0,0 +1,14 @@ +--pretty[='<format>']:: + + Pretty print the contents of the commit logs in a given format, + where '<format>' can be one of 'oneline', 'short', 'medium', + 'full', 'fuller', 'email', 'raw' and 'format:<string>'. + When left out the format default to 'medium'. + +--encoding[=<encoding>]:: + The commit objects record the encoding used for the log message + in their encoding header; this option can be used to tell the + command to re-code the commit log message in the encoding + preferred by the user. For non plumbing commands this + defaults to UTF-8. + diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 534ece4..52247aa 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -1864,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: @@ -1939,7 +1939,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 -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 |