diff options
Diffstat (limited to 'Documentation')
40 files changed, 713 insertions, 169 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index 62dbd9ac7c..0cfdc36b44 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -31,11 +31,11 @@ MAN7_TXT += gittutorial.txt MAN7_TXT += gitworkflows.txt MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT) -MAN_XML=$(patsubst %.txt,%.xml,$(MAN_TXT)) -MAN_HTML=$(patsubst %.txt,%.html,$(MAN_TXT)) +MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT)) +MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT)) OBSOLETE_HTML = git-remote-helpers.html -DOC_HTML=$(MAN_HTML) $(OBSOLETE_HTML) +DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML) ARTICLES = howto-index ARTICLES += everyday @@ -74,35 +74,35 @@ SP_ARTICLES += technical/api-index 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 -htmldir?=$(prefix)/share/doc/git-doc -pdfdir?=$(prefix)/share/doc/git-doc -mandir?=$(prefix)/share/man -man1dir=$(mandir)/man1 -man5dir=$(mandir)/man5 -man7dir=$(mandir)/man7 -# DESTDIR= +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 +htmldir ?= $(prefix)/share/doc/git-doc +infodir ?= $(prefix)/share/info +pdfdir ?= $(prefix)/share/doc/git-doc +mandir ?= $(prefix)/share/man +man1dir = $(mandir)/man1 +man5dir = $(mandir)/man5 +man7dir = $(mandir)/man7 +# DESTDIR = ASCIIDOC = asciidoc ASCIIDOC_EXTRA = MANPAGE_XSL = manpage-normal.xsl XMLTO = xmlto XMLTO_EXTRA = -INSTALL?=install +INSTALL ?= install RM ?= rm -f MAN_REPO = ../../git-manpages HTML_REPO = ../../git-htmldocs -infodir?=$(prefix)/share/info -MAKEINFO=makeinfo -INSTALL_INFO=install-info -DOCBOOK2X_TEXI=docbook2x-texi -DBLATEX=dblatex +MAKEINFO = makeinfo +INSTALL_INFO = install-info +DOCBOOK2X_TEXI = docbook2x-texi +DBLATEX = dblatex ifndef PERL_PATH PERL_PATH = /usr/bin/perl endif diff --git a/Documentation/RelNotes/1.8.4.txt b/Documentation/RelNotes/1.8.4.txt new file mode 100644 index 0000000000..b85f16b378 --- /dev/null +++ b/Documentation/RelNotes/1.8.4.txt @@ -0,0 +1,334 @@ +Git v1.8.4 Release Notes +======================== + +Updates since v1.8.3 +-------------------- + +Foreign interfaces, subsystems and ports. + + * Git-gui has been updated to its 0.18.0 version. + + * MediaWiki remote helper (in contrib/) has been updated to use the + credential helper interface from Git.pm. + + * Update build for Cygwin 1.[57]. Torsten Bögershausen reports that + this is fine with Cygwin 1.7 ($gmane/225824) so let's try moving it + ahead. + + * The credential helper to talk to keychain on OS X (in contrib/) has + been updated to kick in not just when talking http/https but also + imap(s) and smtp. + + * Remote transport helper has been updated to report errors and + maintain ref hierarchy used to keep track of its own state better. + + * With "export" remote-helper protocol, (1) a push that tries to + update a remote ref whose name is different from the pushing side + does not work yet, and (2) the helper may not know how to do + --dry-run; these problematic cases are disabled for now. + + * git-remote-hg/bzr (in contrib/) updates. + + * git-remote-mw (in contrib/) hints users to check the certificate, + when https:// connection failed. + + +UI, Workflows & Features + + * Having multiple "fixup!" on a line in the rebase instruction sheet + did not work very well with "git rebase -i --autosquash". + + * "git log" learned the "--author-date-order" option, with which the + output is topologically sorted and commits in parallel histories + are shown intermixed together based on the author timestamp. + + * Various subcommands of "git submodule" refused to run from anywhere + other than the top of the working tree of the superproject, but + they have been taught to let you run from a subdirectory. + + * "git diff" learned a mode that ignores hunks whose change consists + only of additions and removals of blank lines, which is the same as + "diff -B" (ignore blank lines) of GNU diff. + + * "git rm" gives a single message followed by list of paths to report + multiple paths that cannot be removed. + + * "git rebase" can be told with ":/look for this string" syntax commits + to replay the changes onto and where the work to be replayed begins. + + * Many tutorials teach users to set "color.ui" to "auto" as the first + thing after you set "user.name/email" to introduce yourselves to + Git. Now the variable defaults to "auto". + + * On Cygwin, "cygstart" is now recognised as a possible way to start + a web browser (used in "help -w" and "instaweb" among others). + +### * "git status" learned status.branch and status.short configuration +### variables to use --branch and --short options by default (override +### with --no-branch and --no-short options from the command line). + + * "git cmd <name>", when <name> happens to be a 40-hex string, + directly uses the 40-hex string as an object name, even if a ref + "refs/<some hierarchy>/<name>" exists. This disambiguation order + is unlikely to change, but we should warn about the ambiguity just + like we warn when more than one refs/ hierachies share the same + name. + + * "git rebase" learned "--[no-]autostash" option to save local + changes instead of refusing to run (to which people's normal + response was to stash them and re-run). This introduced a corner + case breakage to "git am --abort" but it has been fixed. + + * Instead of typing four capital letters "HEAD", you can say "@" now, + e.g. "git log @". + + * "check-ignore" (new feature since 1.8.2) has been updated to work + more like "check-attr" over bidi-pipes. + + * "git describe" learned "--first-parent" option to limit its closest + tagged commit search to the first-parent chain. + + * "git merge foo" that might have meant "git merge origin/foo" is + diagnosed with a more informative error message. + + * "git log -L<line>,<range>:<filename>" has been added. This may + still have leaks and rough edges, though. + + * We used the approxidate() parser for "--expire=<timestamp>" options + of various commands, but it is better to treat --expire=all and + --expire=now a bit more specially than using the current timestamp. + "git gc" and "git reflog" have been updated with a new parsing + function for expiry dates. + + * Updates to completion (both bash and zsh) helpers. + + * The behaviour of the "--chain-reply-to" option of "git send-email" + have changed at 1.7.0, and we added a warning/advice message to + help users adjust to the new behaviour back then, but we kept it + around for too long. The message has finally been removed. + + * "git fetch origin master" unlike "git fetch origin" or "git fetch" + did not update "refs/remotes/origin/master"; this was an early + design decision to keep the update of remote tracking branches + predictable, but in practice it turns out that people find it more + convenient to opportunistically update them whenever we have a + chance, and we have been updating them when we run "git push" which + already breaks the original "predictability" anyway. + + * The configuration variable core.checkstat was advertised in the + documentation but the code expected core.statinfo instead. + For now, we accept both core.checkstat and core.statinfo, but the + latter will be removed in the longer term. + + +Performance, Internal Implementation, etc. + + * The original way to specify remote repository using .git/branches/ + used to have a nifty feature. The code to support the feature was + still in a function but the caller was changed not to call it 5 + years ago, breaking that feature and leaving the supporting code + unreachable. The dead code has been removed. + + * "git pack-refs" that races with new ref creation or deletion have + been susceptible to lossage of refs under right conditions, which + has been tightened up. + + * We read loose and packed rerferences in two steps, but after + deciding to read a loose ref but before actually opening it to read + it, another process racing with us can unlink it, which would cause + us to barf. The codepath has been updated to retry when such a + race is detected, instead of outright failing. + + * Uses of the platform fnmatch(3) function (many places in the code, + matching pathspec, .gitignore and .gitattributes to name a few) + have been replaced with wildmatch, allowing "foo/**/bar" that would + match foo/bar, foo/a/bar, foo/a/b/bar, etc. + + * Memory ownership and lifetime rules for what for-each-ref feeds to + its callbacks have been clarified (in short, "you do not own it, so + make a copy if you want to keep it"). + + * The revision traversal logic to improve culling of irrelevant + parents while traversing a mergy history has been updated. + + * Some leaks in unpack-trees (used in merge, cherry-pick and other + codepaths) have been plugged. + + * The codepath to read from marks files in fast-import/export did not + have to accept anything but 40-hex representation of the object + name. Further, fast-export did not need full in-core object + representation to have parsed wen reading from them. These + codepaths have been optimized by taking advantage of these access + patterns. + + * Object lookup logic, when the object hashtable starts to become + crowded, has been optimized. + + * When TEST_OUTPUT_DIRECTORY setting is used, it was handled somewhat + inconsistently between the test framework and t/Makefile, and logic + to summarize the results looked at a wrong place. + + * "git clone" uses a lighter-weight implementation when making sure + that the history behind refs are complete. + + * Many warnings from sparse source checker in compat/ area has been + squelched. + + * The code to reading and updating packed-refs file has been updated, + correcting corner case bugs. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v1.8.3 +------------------ + +Unless otherwise noted, all the fixes since v1.8.3 in the maintenance +track are contained in this release (see release notes to them for +details). + + * The configuration variable column.ui was poorly documented. + (merge 5e62cc1 rr/column-doc later to maint). + + * "git name-rev --refs=tags/v*" were forbidden, which was a bit + inconvenient (you had to give a pattern to match refs fully, like + --refs=refs/tags/v*). + (merge 98c5c4a nk/name-rev-abbreviated-refs later to maint). + + * "git apply" parsed patches that add new files, generated by + programs other than Git, incorrectly. This is an old breakage in + v1.7.11 and will need to be merged down to the maintanance tracks. + (merge 212eb96 tr/maint-apply-non-git-patch-parsefix later to maint). + + * Older cURL wanted piece of memory we call it with to be stable, but + we updated the auth material after handing it to a call. + (merge a94cf2c bc/http-keep-memory-given-to-curl later to maint). + + * "git pull" into nothing trashed "local changes" that were in the + index, and this avoids it. + (merge b4dc085 jk/pull-into-dirty-unborn later to maint). + + * Many "git submodule" operations do not work on a submodule at a + path whose name is not in ASCII. + (merge bed9470 fg/submodule-non-ascii-path later to maint). + + * "cherry-pick" had a small leak in an error codepath. + (merge 706728a fc/sequencer-plug-leak later to maint). + + * Logic used by git-send-email to suppress cc mishandled names like + "A U. Thor" <author@example.xz>, where the human readable part + needs to be quoted (the user input may not have the double quotes + around the name, and comparison was done between quoted and + unquoted strings). It also mishandled names that need RFC2047 + quoting. + (merge 1495266 mt/send-email-cc-match-fix later to maint). + + * Call to discard_cache/discard_index (used when we use different + contents of the index in-core, in many operations like commit, + apply, and merge) used to leak memory that held the array of index + entries, which has been plugged. + (merge a0fc4db rs/discard-index-discard-array later to maint). + + * "gitweb" forgot to clear a global variable $search_regexp upon each + request, mistakenly carrying over the previous search to a new one + when used as a persistent CGI. + (merge ca7a5dc cm/gitweb-project-list-persistent-cgi-fix later to maint). + + * The wildmatch engine did not honor WM_CASEFOLD option correctly. + (merge b79c0c3 ar/wildmatch-foldcase later to maint). + + * "git log -c --follow $path" segfaulted upon hitting the commit that + renamed the $path being followed. + (merge 46ec510 cb/log-follow-with-combined later to maint). + + * When a reflog notation is used for implicit "current branch", we + did not say which branch and worse said "branch ''". + (merge 305ebea rr/die-on-missing-upstream later to maint). + + * "difftool --dir-diff" did not copy back changes made by the + end-user in the diff tool backend to the working tree in some + cases. + (merge 32eaf1d ks/difftool-dir-diff-copy-fix later to maint). + + * "git push $there HEAD:branch" did not resolve HEAD early enough, so + it was easy to flip it around while push is still going on and push + out a branch that the user did not originally intended when the + command was started. + (merge 0f075b2 rr/push-head later to maint). + + * The bash prompt code (in contrib/) displayed the name of the branch + being rebased when "rebase -i/-m/-p" modes are in use, but not the + plain vanilla "rebase". + (merge 1306321 fc/show-branch-in-rebase-am later to maint). + + * Handling of negative exclude pattern for directories "!dir" was + broken in the update to v1.8.3. + (merge c3c327d kb/status-ignored-optim-2 later to maint). + + * zsh prompt script that borrowed from bash prompt script did not + work due to slight differences in array variable notation between + these two shells. + (merge d0583da tg/maint-zsh-svn-remote-prompt later to maint). + + * An entry for "file://" scheme in the enumeration of URL types Git + can take in the HTML documentation was made into a clickable link + by mistake. + (merge 4c32e36 nd/urls-doc-no-file-hyperlink-fix later to maint). + + * "git push --[no-]verify" was not documented. + (merge 90d32d1 tr/push-no-verify-doc later to maint). + + * Stop installing the git-remote-testpy script that is only used for + testing. + (merge 416fda6 fc/makefile later to maint). + + * "git commit --allow-empty-message -m ''" should not start an + editor. + (merge 2520677 rs/commit-m-no-edit later to maint). + + * "git merge @{-1}~22" was rewritten to "git merge frotz@{1}~22" + incorrectly when your previous branch was "frotz" (it should be + rewritten to "git merge frotz~22" instead). + (merge 84cf246 jc/strbuf-branchname-fix later to maint). + + * "git diff -c -p" was not showing a deleted line from a hunk when + another hunk immediately begins where the earlier one ends. + (merge aac3857 mk/combine-diff-context-horizon-fix later to maint). + + * "git log --ancestry-path A...B" did not work as expected, as it did + not pay attention to the fact that the merge base between A and B + was the bottom of the range being specified. + (merge a765499 kb/ancestry-path-threedots later to maint). + + * Mac OS X does not like to write(2) more than INT_MAX number of + bytes; work it around by chopping write(2) into smaller pieces. + (merge 6c642a8 fc/macos-x-clipped-write later to maint). + + * Newer MacOS X encourages the programs to compile and link with + their CommonCrypto, not with OpenSSL. + (merge be4c828 da/darwin later to maint). + + * "git clone foo/bar:baz" cannot be a request to clone from a remote + over git-over-ssh specified in the scp style. This case is now + detected and clones from a local repository at "foo/bar:baz". + (merge 6000334 nd/clone-local-with-colon later to maint). + + * When $HOME is misconfigured to point at an unreadable directory, we + used to complain and die. Loosen the check. + (merge 4698c8f jn/config-ignore-inaccessible later to maint). + + * "git subtree" (in contrib/) had one codepath with loose error + checks to lose data at the remote side. + (merge 3212d56 jk/subtree-do-not-push-if-split-fails later to maint). + + * "git fetch" into a shallow repository from a repository that does + not know about the shallow boundary commits (e.g. a different fork + from the repository the current shallow repository was cloned from) + did not work correctly. + (merge 71d5f93 mh/fetch-into-shallow later to maint). + + * "git checkout foo" DWIMs the intended "upstream" and turns it into + "git checkout -t -b foo remotes/origin/foo". This codepath has been + updated to correctly take existing remote definitions into account. + (merge 229177a jh/checkout-auto-tracking later to maint). diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index b0d31df0e7..e9f984ba01 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -9,28 +9,11 @@ --show-stats:: Include additional statistics at the end of blame output. --L <start>,<end>:: +-L <start>,<end>, -L :<regex>:: Annotate only the given line range. <start> and <end> can take one of these forms: - - number -+ -If <start> or <end> is a number, it specifies an -absolute line number (lines count from 1). -+ - -- /regex/ -+ -This form will use the first line matching the given -POSIX regex. If <end> is a regex, it will search -starting at the line given by <start>. -+ - -- +offset or -offset -+ -This is only valid for <end> and will specify a number -of lines before or after the line given by <start>. -+ +include::line-range-format.txt[] -l:: Show long rev (Default: off). diff --git a/Documentation/config.txt b/Documentation/config.txt index 6e53fc5074..b4d4887bd7 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -199,6 +199,9 @@ advice.*:: amWorkDir:: Advice that shows the location of the patch file when linkgit:git-am[1] fails to apply it. + rmHints:: + In case of failure in the output of linkgit:git-rm[1], + show directions on how to proceed from the current state. -- core.fileMode:: @@ -919,17 +922,21 @@ color.ui:: as `color.diff` and `color.grep` that control the use of color per command family. Its scope will expand as more commands learn configuration to set a default for the `--color` option. Set it - to `always` if you want all output not intended for machine - consumption to use color, to `true` or `auto` if you want such - output to use color when written to the terminal, or to `false` or - `never` if you prefer Git commands not to use color unless enabled - explicitly with some other configuration or the `--color` option. + to `false` or `never` if you prefer Git commands not to use + color unless enabled explicitly with some other configuration + or the `--color` option. Set it to `always` if you want all + output not intended for machine consumption to use color, to + `true` or `auto` (this is the default since Git 1.8.4) if you + want such output to use color when written to the terminal. column.ui:: Specify whether supported commands should output in columns. This variable consists of a list of tokens separated by spaces or commas: + +These options control when the feature should be enabled +(defaults to 'never'): ++ -- `always`;; always show in columns @@ -937,19 +944,30 @@ column.ui:: never show in columns `auto`;; show in columns if the output is to the terminal +-- ++ +These options control layout (defaults to 'column'). Setting any +of these implies 'always' if none of 'always', 'never', or 'auto' are +specified. ++ +-- `column`;; - fill columns before rows (default) + fill columns before rows `row`;; fill rows before columns `plain`;; show in one column +-- ++ +Finally, these options can be combined with a layout option (defaults +to 'nodense'): ++ +-- `dense`;; make unequal size columns to utilize more space `nodense`;; make equal size columns -- -+ -This option defaults to 'never'. column.branch:: Specify whether to output branch listing in `git branch` in columns. @@ -1867,6 +1885,14 @@ rebase.stat:: rebase.autosquash:: If set to true enable '--autosquash' option by default. +rebase.autostash:: + When set to true, automatically create a temporary stash + before the operation begins, and apply it after the operation + ends. This means that you can run rebase on a dirty worktree. + However, use with care: the final stash application after a + successful rebase might result in non-trivial conflicts. + Defaults to false. + receive.autogc:: By default, git-receive-pack will run "git-gc --auto" after receiving data from git-push and updating refs. You can stop diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index a85288f23e..19f78a7d5c 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -461,6 +461,9 @@ endif::git-format-patch[] differences even if one line has whitespace where the other line has none. +--ignore-blank-lines:: + Ignore changes whose lines are all blank. + --inter-hunk-context=<lines>:: Show the context between diff hunks, up to the specified number of lines, thereby fusing hunks that are close to each other. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 9cb649673d..ba1fe49582 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -61,7 +61,7 @@ endif::git-pull[] ifndef::git-pull[] -t:: --tags:: - This is a short-hand for giving "refs/tags/*:refs/tags/*" + This is a short-hand for giving `refs/tags/*:refs/tags/*` refspec from the command line, to ask all tags to be fetched and stored locally. Because this acts as an explicit refspec, the default refspecs (configured with the diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 5bbe7b6d10..54d8461d61 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -132,7 +132,7 @@ default. You can use `--no-utf8` to override this. --resolvemsg=<msg>:: When a patch failure occurs, <msg> will be printed to the screen before exiting. This overrides the - standard message informing you to use `--resolved` + standard message informing you to use `--continue` or `--skip` to handle the failure. This is solely for internal use between 'git rebase' and 'git am'. @@ -176,7 +176,7 @@ aborts in the middle. You can recover from this in one of two ways: . hand resolve the conflict in the working directory, and update the index file to bring it into a state that the patch should - have produced. Then run the command with the '--resolved' option. + have produced. Then run the command with the '--continue' option. The command refuses to process new mailboxes until the current operation is finished, so if you decide to start over from scratch, diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 9a05c2b3d2..6cea7f1ce1 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -8,9 +8,9 @@ git-blame - Show what revision and author last modified each line of a file SYNOPSIS -------- [verse] -'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L n,m] - [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--abbrev=<n>] - [<rev> | --contents <file> | --reverse <rev>] [--] <file> +'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] + [-L n,m | -L :fn] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] + [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>] [--] <file> DESCRIPTION ----------- diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 5abdbaa51c..a7be80d48b 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -56,6 +56,11 @@ being queried and <info> can be either: 'set';; when the attribute is defined as true. <value>;; when a value has been assigned to the attribute. +Buffering happens as documented under the `GIT_FLUSH` option in +linkgit:git[1]. The caller is responsible for avoiding deadlocks +caused by overfilling an input buffer or reading from an empty output +buffer. + EXAMPLES -------- diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index 7f5601bda5..d2df487aa2 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -39,6 +39,12 @@ OPTIONS below). If `--stdin` is also given, input paths are separated with a NUL character instead of a linefeed character. +-n, --non-matching:: + Show given paths which don't match any pattern. This only + makes sense when `--verbose` is enabled, otherwise it would + not be possible to distinguish between paths which match a + pattern and those which don't. + OUTPUT ------ @@ -65,6 +71,20 @@ are also used instead of colons and hard tabs: <source> <NULL> <linenum> <NULL> <pattern> <NULL> <pathname> <NULL> +If `-n` or `--non-matching` are specified, non-matching pathnames will +also be output, in which case all fields in each output record except +for <pathname> will be empty. This can be useful when running +non-interactively, so that files can be incrementally streamed to +STDIN of a long-running check-ignore process, and for each of these +files, STDOUT will indicate whether that file matched a pattern or +not. (Without this option, it would be impossible to tell whether the +absence of output for a given file meant that it didn't match any +pattern, or that the output hadn't been generated yet.) + +Buffering happens as documented under the `GIT_FLUSH` option in +linkgit:git[1]. The caller is responsible for avoiding deadlocks +caused by overfilling an input buffer or reading from an empty output +buffer. EXIT STATUS ----------- diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index a49be1bab4..fc02959ba4 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -54,6 +54,8 @@ Git imposes the following rules on how references are named: . They cannot contain a sequence `@{`. +. They cannot be the single character `@`. + . They cannot contain a `\`. These rules make it easy for shell script based tools to parse diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index a0727d7759..450f158779 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -239,8 +239,8 @@ Examples * Clone from upstream: + ------------ -$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6 -$ cd my2.6 +$ git clone git://git.kernel.org/pub/scm/.../linux.git my-linux +$ cd my-linux $ make ------------ @@ -257,10 +257,10 @@ $ git show-branch * Clone from upstream while borrowing from an existing local directory: + ------------ -$ git clone --reference my2.6 \ - git://git.kernel.org/pub/scm/.../linux-2.7 \ - my2.7 -$ cd my2.7 +$ git clone --reference /git/linux.git \ + git://git.kernel.org/pub/scm/.../linux.git \ + my-linux +$ cd my-linux ------------ @@ -271,13 +271,6 @@ $ git clone --bare -l /home/proj/.git /pub/scm/proj.git ------------ -* Create a repository on the kernel.org machine that borrows from Linus: -+ ------------- -$ git clone --bare -l -s /pub/scm/.../torvalds/linux-2.6.git \ - /pub/scm/.../me/subsys-2.6.git ------------- - GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 606f00c3b8..fbad05e46f 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -114,6 +114,15 @@ rather than from all available files. + See also <<FILES>>. +--local:: + For writing options: write to the repository .git/config file. + This is the default behavior. ++ +For reading options: read only from the repository .git/config rather than +from all available files. ++ +See also <<FILES>>. + -f config-file:: --file config-file:: Use the given config file instead of the one specified by GIT_CONFIG. diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 28e5ec0e2c..9439cd6d56 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -88,6 +88,11 @@ OPTIONS --always:: Show uniquely abbreviated commit object as fallback. +--first-parent:: + Follow only the first parent commit upon seeing a merge commit. + This is useful when you wish to not match tags on branches merged + in the history of the target commit. + EXAMPLES -------- @@ -149,7 +154,9 @@ is found, its name will be output and searching will stop. If an exact match was not found, 'git describe' will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an -abbreviation of the input committish's SHA-1. +abbreviation of the input committish's SHA-1. If '--first-parent' was +specified then the walk will only consider the first parent of each +commit. If multiple tags were found during the walk then the tag which has the fewest commits different from the input committish will be diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index a7b46208f6..78d6d50489 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -18,8 +18,8 @@ SYNOPSIS DESCRIPTION ----------- Show changes between the working tree and the index or a tree, changes -between the index and a tree, changes between two trees, or changes -between two files on disk. +between the index and a tree, changes between two trees, changes between +two blob objects, or changes between two files on disk. 'git diff' [--options] [--] [<path>...]:: @@ -56,11 +56,6 @@ directories. This behavior can be forced by --no-index. This is to view the changes between two arbitrary <commit>. -'git diff' [options] <blob> <blob>:: - - This form is to view the differences between the raw - contents of two blob objects. - 'git diff' [--options] <commit>..<commit> [--] [<path>...]:: This is synonymous to the previous form. If <commit> on @@ -87,6 +82,11 @@ and the range notations ("<commit>..<commit>" and "<commit>\...<commit>") do not mean a range as defined in the "SPECIFYING RANGES" section in linkgit:gitrevisions[7]. +'git diff' [options] <blob> <blob>:: + + This form is to view the differences between the raw + contents of two blob objects. + OPTIONS ------- :git-diff: 1 diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index efb03806f5..85f1f30fdf 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -141,7 +141,7 @@ Limitations ----------- Since 'git fast-import' cannot tag trees, you will not be -able to export the linux-2.6.git repository completely, as it contains +able to export the linux.git repository completely, as it contains a tag referencing a tree instead of a commit. GIT diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index b370b025b8..2402ed6828 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -62,8 +62,9 @@ automatic consolidation of packs. --prune=<date>:: Prune loose objects older than date (default is 2 weeks ago, - overridable by the config variable `gc.pruneExpire`). This - option is on by default. + overridable by the config variable `gc.pruneExpire`). + --prune=all prunes loose objects regardless of their age. + --prune is on by default. --no-prune:: Do not prune any loose objects. diff --git a/Documentation/git-index-pack.txt b/Documentation/git-index-pack.txt index bde8eec30d..7a4e055520 100644 --- a/Documentation/git-index-pack.txt +++ b/Documentation/git-index-pack.txt @@ -74,6 +74,9 @@ OPTIONS --strict:: Die, if the pack contains broken objects or links. +--check-self-contained-and-connected:: + Die if the pack contains broken links. For internal use only. + --threads=<n>:: Specifies the number of threads to spawn when resolving deltas. This requires that index-pack be compiled with diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index a976534ab8..2ea79ba168 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -62,6 +62,19 @@ produced by --stat etc. Note that only message is considered, if also a diff is shown its size is not included. +-L <start>,<end>:<file>, -L :<regex>:<file>:: + + Trace the evolution of the line range given by "<start>,<end>" + (or the funcname regex <regex>) within the <file>. You may + not give any pathspec limiters. This is currently limited to + a walk starting from a single revision, i.e., you may only + give zero or one positive revision arguments. + You can specify this option more than once. ++ +<start> and <end> can take one of these forms: + +include::line-range-format.txt[] + <revision range>:: Show only commits in the specified revision range. When no <revision range> is specified, it defaults to `HEAD` (i.e. the @@ -115,9 +128,9 @@ Examples in the "release" branch, along with the list of paths each commit modifies. -`git log --follow builtin-rev-list.c`:: +`git log --follow builtin/rev-list.c`:: - Shows the commits that changed builtin-rev-list.c, including + Shows the commits that changed builtin/rev-list.c, including those commits that occurred before the file was given its present name. @@ -140,6 +153,11 @@ Examples This makes sense only when following a strict policy of merging all topic branches when staying on a single integration branch. +git log -L '/int main/',/^}/:main.c:: + + Shows how the function `main()` in the file 'main.c' evolved + over time. + `git log -3`:: Limits the number of commits to show to 3. diff --git a/Documentation/git-ls-remote.txt b/Documentation/git-ls-remote.txt index 774de5e9d9..2e22915eb8 100644 --- a/Documentation/git-ls-remote.txt +++ b/Documentation/git-ls-remote.txt @@ -48,9 +48,9 @@ OPTIONS exit without talking to the remote. <repository>:: - Location of the repository. The shorthand defined in - $GIT_DIR/branches/ can be used. Use "." (dot) to list references in - the local repository. + The "remote" repository to query. This parameter can be + either a URL or the name of a remote (see the GIT URLS and + REMOTES sections of linkgit:git-fetch[1]). <refs>...:: When unspecified, all references, after filtering done @@ -70,9 +70,8 @@ EXAMPLES $ git ls-remote http://www.kernel.org/pub/scm/git/git.git master pu rc 5fe978a5381f1fbad26a80e682ddd2a401966740 refs/heads/master c781a84b5204fb294c9ccc79f8b3baceeb32c061 refs/heads/pu - b1d096f2926c4e37c9c0b6a7bf2119bedaa277cb refs/heads/rc - $ echo http://www.kernel.org/pub/scm/git/git.git >.git/branches/public - $ git ls-remote --tags public v\* + $ git remote add korg http://www.kernel.org/pub/scm/git/git.git + $ git ls-remote --tags korg v\* d6602ec5194c87b0fc87103ca4d67251c76f233a refs/tags/v0.99 f25a265a342aed6041ab0cc484224d9ca54b6f41 refs/tags/v0.99.1 c5db5456ae3b0873fc659c19fafdde22313cc441 refs/tags/v0.99.2 diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index 67ca99cd92..8c7f2f66d8 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -56,8 +56,8 @@ especially if those changes were further modified after the merge was started), 'git merge --abort' will in some cases be unable to reconstruct the original (pre-merge) changes. Therefore: -*Warning*: Running 'git merge' with uncommitted changes is -discouraged: while possible, it leaves you in a state that is hard to +*Warning*: Running 'git merge' with non-trivial uncommitted changes is +discouraged: while possible, it may leave you in a state that is hard to back out of in the case of a conflict. diff --git a/Documentation/git-name-rev.txt b/Documentation/git-name-rev.txt index ad1d1468c9..6b0f1ba75f 100644 --- a/Documentation/git-name-rev.txt +++ b/Documentation/git-name-rev.txt @@ -25,7 +25,8 @@ OPTIONS Do not use branch names, but only tags to name the commits --refs=<pattern>:: - Only use refs whose names match a given shell pattern. + Only use refs whose names match a given shell pattern. The pattern + can be one of branch name, tag name or fully qualified ref name. --all:: List all commits reachable from all refs diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index df5be268ba..f7dfe48d28 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -136,6 +136,15 @@ already exists on the remote side. not an ancestor of the local ref used to overwrite it. This flag disables the check. This can cause the remote repository to lose commits; use it with care. + Note that `--force` applies to all the refs that are pushed, + hence using it with `push.default` set to `matching` or with + multiple push destinations configured with `remote.*.push` + may overwrite refs other than the current branch (including + local refs that are strictly behind their remote counterpart). + To force a push to only one branch, use a `+` in front of the + refspec to push (e.g `git push origin +master` to force a push + to the `master` branch). See the `<refspec>...` section above + for details. --repo=<repository>:: This option is only relevant if no <repository> argument is diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index aca840525e..6b2e1c86ab 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -208,6 +208,9 @@ rebase.stat:: rebase.autosquash:: If set to true enable '--autosquash' option by default. +rebase.autostash:: + If set to true enable '--autostash' option by default. + OPTIONS ------- --onto <newbase>:: @@ -386,7 +389,9 @@ squash/fixup series. the same ..., automatically modify the todo list of rebase -i so that the commit marked for squashing comes right after the commit to be modified, and change the action of the moved - commit from `pick` to `squash` (or `fixup`). + commit from `pick` to `squash` (or `fixup`). Ignores subsequent + "fixup! " or "squash! " after the first, in case you referred to an + earlier fixup/squash with `git commit --fixup/--squash`. + This option is only valid when the '--interactive' option is used. + @@ -394,6 +399,13 @@ If the '--autosquash' option is enabled by default using the configuration variable `rebase.autosquash`, this option can be used to override and disable this setting. +--[no-]autostash:: + Automatically create a temporary stash before the operation + begins, and apply it after the operation ends. This means + that you can run rebase on a dirty worktree. However, use + with care: the final stash application after a successful + rebase might result in non-trivial conflicts. + --no-ff:: With --interactive, cherry-pick all rebased commits instead of fast-forwarding over the unchanged ones. This ensures that the diff --git a/Documentation/git-reflog.txt b/Documentation/git-reflog.txt index fb8697ea4c..70791b9fd8 100644 --- a/Documentation/git-reflog.txt +++ b/Documentation/git-reflog.txt @@ -67,14 +67,19 @@ them. --expire=<time>:: Entries older than this time are pruned. Without the option it is taken from configuration `gc.reflogExpire`, - which in turn defaults to 90 days. + which in turn defaults to 90 days. --expire=all prunes + entries regardless of their age; --expire=never turns off + pruning of reachable entries (but see --expire-unreachable). --expire-unreachable=<time>:: Entries older than this time and not reachable from the current tip of the branch are pruned. Without the option it is taken from configuration `gc.reflogExpireUnreachable`, which in turn defaults to - 30 days. + 30 days. --expire-unreachable=all prunes unreachable + entries regardless of their age; --expire-unreachable=never + turns off early pruning of unreachable entries (but see + --expire). --all:: Instead of listing <refs> explicitly, prune all refs. diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt index 581bb4c413..9c3e3bf83a 100644 --- a/Documentation/git-remote.txt +++ b/Documentation/git-remote.txt @@ -187,18 +187,25 @@ Examples $ git remote origin $ git branch -r -origin/master -$ git remote add linux-nfs git://linux-nfs.org/pub/linux/nfs-2.6.git + origin/HEAD -> origin/master + origin/master +$ git remote add staging git://git.kernel.org/.../gregkh/staging.git $ git remote -linux-nfs origin -$ git fetch -* refs/remotes/linux-nfs/master: storing branch 'master' ... - commit: bf81b46 +staging +$ git fetch staging +... +From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging + * [new branch] master -> staging/master + * [new branch] staging-linus -> staging/staging-linus + * [new branch] staging-next -> staging/staging-next $ git branch -r -origin/master -linux-nfs/master -$ git checkout -b nfs linux-nfs/master + origin/HEAD -> origin/master + origin/master + staging/master + staging/staging-linus + staging/staging-next +$ git checkout -b staging staging/master ... ------------ diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 947d62fd25..993903c9f1 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -59,6 +59,22 @@ OPTIONS If there is no parameter given by the user, use `<arg>` instead. +--prefix <arg>:: + Behave as if 'git rev-parse' was invoked from the `<arg>` + subdirectory of the working tree. Any relative filenames are + resolved as if they are prefixed by `<arg>` and will be printed + in that form. ++ +This can be used to convert arguments to a command run in a subdirectory +so that they can still be used after moving to the top-level of the +repository. For example: ++ +---- +prefix=$(git rev-parse --show-prefix) +cd "$(git rev-parse --show-toplevel)" +eval "set -- $(git rev-parse --sq --prefix "$prefix" "$@")" +---- + --verify:: Verify that exactly one parameter is provided, and that it can be turned into a raw 20-byte SHA-1 that can be used to diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 711ffe17a7..db7e803038 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -13,10 +13,11 @@ SYNOPSIS 'git stash' drop [-q|--quiet] [<stash>] 'git stash' ( pop | apply ) [--index] [-q|--quiet] [<stash>] 'git stash' branch <branchname> [<stash>] -'git stash' [save [--patch] [-k|--[no-]keep-index] [-q|--quiet] +'git stash' [save [-p|--patch] [-k|--[no-]keep-index] [-q|--quiet] [-u|--include-untracked] [-a|--all] [<message>]] 'git stash' clear -'git stash' create +'git stash' create [<message>] +'git stash' store [-m|--message <message>] [-q|--quiet] <commit> DESCRIPTION ----------- @@ -151,7 +152,15 @@ create:: Create a stash (which is a regular commit object) and return its object name, without storing it anywhere in the ref namespace. + This is intended to be useful for scripts. It is probably not + the command you want to use; see "save" above. +store:: + + Store a given stash created via 'git stash create' (which is a + dangling merge commit) in the stash ref, updating the stash + reflog. This is intended to be useful for scripts. It is + probably not the command you want to use; see "save" above. DISCUSSION ---------- diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index ba79cb4f35..5aec4ecffb 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -34,6 +34,7 @@ The following browsers (or commands) are currently supported: * dillo * open (this is the default under Mac OS X GUI) * start (this is the default under MinGW) +* cygstart (this is the default under Cygwin) Custom commands may also be specified. diff --git a/Documentation/git.txt b/Documentation/git.txt index 8c41881b37..b738a40e6b 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -53,9 +53,9 @@ Documentation for older releases are available here: * link:v1.8.2.3/git.html[documentation for release 1.8.2.3] * release notes for - link:RelNotes/1.8.2.3.txt[1.8.2.3]. - link:RelNotes/1.8.2.2.txt[1.8.2.2]. - link:RelNotes/1.8.2.1.txt[1.8.2.1]. + link:RelNotes/1.8.2.3.txt[1.8.2.3], + link:RelNotes/1.8.2.2.txt[1.8.2.2], + link:RelNotes/1.8.2.1.txt[1.8.2.1], link:RelNotes/1.8.2.txt[1.8.2]. * link:v1.8.1.6/git.html[documentation for release 1.8.1.6] @@ -816,8 +816,9 @@ for further details. 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', - and 'git whatchanged' will force a flush of the output stream - after each commit-oriented record have been flushed. If this + 'git check-attr', 'git check-ignore', and 'git whatchanged' will + force a flush of the output stream after each record have been + flushed. If this variable is set to "0", the output of these commands will be done using completely buffered I/O. If this environment variable is not set, Git will choose buffered or record-oriented flushing @@ -837,6 +838,19 @@ for further details. as a file path and will try to write the trace messages into it. +'GIT_TRACE_PACK_ACCESS':: + If this variable is set to a path, a file will be created at + the given path logging all accesses to any packs. For each + access, the pack file name and an offset in the pack is + recorded. This may be helpful for troubleshooting some + pack-related performance problems. + +'GIT_TRACE_PACKET':: + If this variable is set, it shows a trace of all packets + coming in or out of a given program. This can help with + debugging object negotiation or other protocol issues. Tracing + is turned off at a packet starting with "PACK". + GIT_LITERAL_PATHSPECS:: Setting this variable to `1` will cause Git to treat all pathspecs literally, rather than as glob patterns. For example, diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt index da746419b3..0827f69139 100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@ -159,11 +159,11 @@ Miscellaneous capabilities carried out. 'refspec' <refspec>:: - This modifies the 'import' capability, allowing the produced - fast-import stream to modify refs in a private namespace - instead of writing to refs/heads or refs/remotes directly. + For remote helpers that implement 'import' or 'export', this capability + allows the refs to be constrained to a private namespace, instead of + writing to refs/heads or refs/remotes directly. It is recommended that all importers providing the 'import' - capability use this. + capability use this. It's mandatory for 'export'. + A helper advertising the capability `refspec refs/heads/*:refs/svn/origin/branches/*` @@ -174,8 +174,8 @@ ref. This capability can be advertised multiple times. The first applicable refspec takes precedence. The left-hand of refspecs advertised with this capability must cover all refs reported by -the list command. If a helper does not need a specific 'refspec' -capability then it should advertise `refspec *:*`. +the list command. If no 'refspec' capability is advertised, +there is an implied `refspec *:*`. 'bidi-import':: This modifies the 'import' capability. diff --git a/Documentation/line-range-format.txt b/Documentation/line-range-format.txt new file mode 100644 index 0000000000..3e7ce72daa --- /dev/null +++ b/Documentation/line-range-format.txt @@ -0,0 +1,25 @@ +- number ++ +If <start> or <end> is a number, it specifies an +absolute line number (lines count from 1). ++ + +- /regex/ ++ +This form will use the first line matching the given +POSIX regex. If <end> is a regex, it will search +starting at the line given by <start>. ++ + +- +offset or -offset ++ +This is only valid for <end> and will specify a number +of lines before or after the line given by <start>. ++ + +- :regex ++ +If the option's argument is of the form :regex, it denotes the range +from the first funcname line that matches <regex>, up to the next +funcname line. ++ diff --git a/Documentation/pull-fetch-param.txt b/Documentation/pull-fetch-param.txt index 94a9d32f1d..18cffc25b8 100644 --- a/Documentation/pull-fetch-param.txt +++ b/Documentation/pull-fetch-param.txt @@ -68,6 +68,11 @@ Some short-cut notations are also supported. + * `tag <tag>` means the same as `refs/tags/<tag>:refs/tags/<tag>`; it requests fetching everything up to the given tag. -* A parameter <ref> without a colon is equivalent to - <ref>: when pulling/fetching, so it merges <ref> into the current - branch without storing the remote branch anywhere locally +ifndef::git-pull[] +* A parameter <ref> without a colon fetches that ref into FETCH_HEAD, +endif::git-pull[] +ifdef::git-pull[] +* A parameter <ref> without a colon merges <ref> into the current + branch, +endif::git-pull[] + and updates the remote-tracking branches (if any). diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 3bdbf5e856..e157ec3fe7 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -271,8 +271,8 @@ See also linkgit:git-reflog[1]. --boundary:: - Output uninteresting commits at the boundary, which are usually - not shown. + Output excluded boundary commits. Boundary commits are + prefixed with `-`. -- @@ -342,13 +342,13 @@ In the following, we will always refer to the same example history to illustrate the differences between simplification settings. We assume that you are filtering for a file `foo` in this commit graph: ----------------------------------------------------------------------- - .-A---M---N---O---P - / / / / / - I B C D E - \ / / / / - `-------------' + .-A---M---N---O---P---Q + / / / / / / + I B C D E Y + \ / / / / / + `-------------' X ----------------------------------------------------------------------- -The horizontal line of history A---P is taken to be the first parent of +The horizontal line of history A---Q is taken to be the first parent of each merge. The commits are: * `I` is the initial commit, in which `foo` exists with contents @@ -367,8 +367,11 @@ each merge. The commits are: `N` and `D` to "foobarbaz"; i.e., it is not TREESAME to any parent. * `E` changes `quux` to "xyzzy", and its merge `P` combines the - strings to "quux xyzzy". Despite appearing interesting, `P` is - TREESAME to all parents. + strings to "quux xyzzy". `P` is TREESAME to `O`, but not to `E`. + +* `X` is an indpendent root commit that added a new file `side`, and `Y` + modified it. `Y` is TREESAME to `X`. Its merge `Q` added `side` to `P`, and + `Q` is TREESAME to `P`, but not to `Y`. 'rev-list' walks backwards through history, including or excluding commits based on whether '\--full-history' and/or parent rewriting @@ -410,10 +413,10 @@ parent lines. the example, we get + ----------------------------------------------------------------------- - I A B N D O + I A B N D O P Q ----------------------------------------------------------------------- + -`P` and `M` were excluded because they are TREESAME to a parent. `E`, +`M` was excluded because it is TREESAME to both parents. `E`, `C` and `B` were all walked, but only `B` was !TREESAME, so the others do not appear. + @@ -431,7 +434,7 @@ Along each parent, prune away commits that are not included themselves. This results in + ----------------------------------------------------------------------- - .-A---M---N---O---P + .-A---M---N---O---P---Q / / / / / I B / D / \ / / / / @@ -441,7 +444,7 @@ themselves. This results in Compare to '\--full-history' without rewriting above. Note that `E` was pruned away because it is TREESAME, but the parent list of P was rewritten to contain `E`'s parent `I`. The same happened for `C` and -`N`. Note also that `P` was included despite being TREESAME. +`N`, and `X`, `Y` and `Q`. In addition to the above settings, you can change whether TREESAME affects inclusion: @@ -471,8 +474,9 @@ history according to the following rules: * Set `C'` to `C`. + * Replace each parent `P` of `C'` with its simplification `P'`. In - the process, drop parents that are ancestors of other parents, and - remove duplicates. + the process, drop parents that are ancestors of other parents or that are + root commits TREESAME to an empty tree, and remove duplicates, but take care + to never drop all parents that we are TREESAME to. + * If after this parent rewriting, `C'` is a root or merge commit (has zero or >1 parents), a boundary commit, or !TREESAME, it remains. @@ -490,7 +494,7 @@ The effect of this is best shown by way of comparing to `---------' ----------------------------------------------------------------------- + -Note the major differences in `N` and `P` over '--full-history': +Note the major differences in `N`, `P` and `Q` over '--full-history': + -- * `N`'s parent list had `I` removed, because it is an ancestor of the @@ -498,6 +502,10 @@ Note the major differences in `N` and `P` over '--full-history': + * `P`'s parent list similarly had `I` removed. `P` was then removed completely, because it had one parent and is TREESAME. ++ +* `Q`'s parent list had `Y` simplified to `X`. `X` was then removed, because it + was a TREESAME root. `Q` was then removed completely, because it had one + parent and is TREESAME. -- Finally, there is a fifth simplification mode available: @@ -617,6 +625,10 @@ By default, the commits are shown in reverse chronological order. Show no parents before all of its children are shown, but otherwise show commits in the commit timestamp order. +--author-date-order:: + Show no parents before all of its children are shown, but + otherwise show commits in the author timestamp order. + --topo-order:: Show no parents before all of its children are shown, and avoid showing commits on multiple lines of history diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index d477b3f6bc..09896a37b1 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -58,6 +58,9 @@ the '$GIT_DIR/refs' directory or from the '$GIT_DIR/packed-refs' file. While the ref name encoding is unspecified, UTF-8 is preferred as some output processing may assume ref names in UTF-8. +'@':: + '@' alone is a shortcut for 'HEAD'. + '<refname>@\{<date>\}', e.g. 'master@\{yesterday\}', 'HEAD@\{5 minutes ago\}':: A ref followed by the suffix '@' with a date specification enclosed in a brace diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index 4a4228b896..f3c1357b7c 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -39,7 +39,7 @@ where options is the bitwise-or of: on bare repositories. This only makes sense when `RUN_SETUP` is also set. -. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`. +. Add `builtin/foo.o` to `BUILTIN_OBJS` in `Makefile`. Additionally, if `foo` is a new command, there are 3 more things to do: diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 32ddc1cf13..0be2b5159f 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -41,6 +41,8 @@ The parse-options API allows: * Boolean long options can be 'negated' (or 'unset') by prepending `no-`, e.g. `--no-abbrev` instead of `--abbrev`. Conversely, options that begin with `no-` can be 'negated' by removing it. + Other long options can be unset (e.g., set string to NULL, set + integer to 0) by prepending `no-`. * Options and non-option arguments can clearly be separated using the `--` option, e.g. `-a -b --option -- --this-is-a-file` indicates that @@ -174,6 +176,10 @@ There are some macros to easily define options: Introduce an option with date argument, see `approxidate()`. The timestamp is put into `int_var`. +`OPT_EXPIRY_DATE(short, long, &int_var, description)`:: + Introduce an option with expiry date argument, see `parse_expiry_date()`. + The timestamp is put into `int_var`. + `OPT_CALLBACK(short, long, &var, arg_str, description, func_ptr)`:: Introduce an option with argument. The argument will be fed into the function given by `func_ptr` @@ -269,10 +275,10 @@ Examples -------- See `test-parse-options.c` and -`builtin-add.c`, -`builtin-clone.c`, -`builtin-commit.c`, -`builtin-fetch.c`, -`builtin-fsck.c`, -`builtin-rm.c` +`builtin/add.c`, +`builtin/clone.c`, +`builtin/commit.c`, +`builtin/fetch.c`, +`builtin/fsck.c`, +`builtin/rm.c` for real-world examples. diff --git a/Documentation/technical/racy-git.txt b/Documentation/technical/racy-git.txt index 6dc82ca5a8..f716d6d97f 100644 --- a/Documentation/technical/racy-git.txt +++ b/Documentation/technical/racy-git.txt @@ -135,9 +135,9 @@ them, and give the same timestamp to the index file: $ git ls-files | git update-index --stdin $ touch -r .datestamp .git/index -This will make all index entries racily clean. The linux-2.6 -project, for example, there are over 20,000 files in the working -tree. On my Athlon 64 X2 3800+, after the above: +This will make all index entries racily clean. The linux project, for +example, there are over 20,000 files in the working tree. On my +Athlon 64 X2 3800+, after the above: $ /usr/bin/time git diff-files 1.68user 0.54system 0:02.22elapsed 100%CPU (0avgtext+0avgdata 0maxresident)k diff --git a/Documentation/urls.txt b/Documentation/urls.txt index 60ba300117..9ccb24677e 100644 --- a/Documentation/urls.txt +++ b/Documentation/urls.txt @@ -11,6 +11,9 @@ and ftps can be used for fetching and rsync can be used for fetching and pushing, but these are inefficient and deprecated; do not use them). +The native transport (i.e. git:// URL) does no authentication and +should be used with caution on unsecured networks. + The following syntaxes may be used with them: - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/path/to/repo.git/ @@ -23,6 +26,12 @@ An alternative scp-like syntax may also be used with the ssh protocol: - {startsb}user@{endsb}host.xz:path/to/repo.git/ +This syntax is only recognized if there are no slashes before the +first colon. This helps differentiate a local path that contains a +colon. For example the local path `foo:bar` could be specified as an +absolute path or `./foo:bar` to avoid being misinterpreted as an ssh +url. + The ssh and git protocols additionally support ~username expansion: - ssh://{startsb}user@{endsb}host.xz{startsb}:port{endsb}/~{startsb}user{endsb}/path/to/repo.git/ diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index e831cc2020..e364007d7c 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -57,17 +57,17 @@ download a copy of an existing repository. If you don't already have a project in mind, here are some interesting examples: ------------------------------------------------ - # Git itself (approx. 10MB download): + # Git itself (approx. 40MB download): $ git clone git://git.kernel.org/pub/scm/git/git.git - # the Linux kernel (approx. 150MB download): -$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git + # the Linux kernel (approx. 640MB download): +$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ------------------------------------------------ The initial clone may be time-consuming for a large project, but you will only need to clone once. -The clone command creates a new directory named after the project (`git` -or `linux-2.6` in the examples above). After you cd into this +The clone command creates a new directory named after the project +(`git` or `linux` in the examples above). After you cd into this directory, you will see that it contains a copy of the project files, called the <<def_working_tree,working tree>>, together with a special top-level directory named `.git`, which contains all the information @@ -431,19 +431,25 @@ You can also track branches from repositories other than the one you cloned from, using linkgit:git-remote[1]: ------------------------------------------------- -$ git remote add linux-nfs git://linux-nfs.org/pub/nfs-2.6.git -$ git fetch linux-nfs -* refs/remotes/linux-nfs/master: storing branch 'master' ... - commit: bf81b46 +$ git remote add staging git://git.kernel.org/.../gregkh/staging.git +$ git fetch staging +... +From git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging + * [new branch] master -> staging/master + * [new branch] staging-linus -> staging/staging-linus + * [new branch] staging-next -> staging/staging-next ------------------------------------------------- New remote-tracking branches will be stored under the shorthand name -that you gave `git remote add`, in this case `linux-nfs`: +that you gave `git remote add`, in this case `staging`: ------------------------------------------------- $ git branch -r -linux-nfs/master -origin/master + origin/HEAD -> origin/master + origin/master + staging/master + staging/staging-linus + staging/staging-next ------------------------------------------------- If you run `git fetch <remote>` later, the remote-tracking branches @@ -455,9 +461,9 @@ a new stanza: ------------------------------------------------- $ cat .git/config ... -[remote "linux-nfs"] - url = git://linux-nfs.org/pub/nfs-2.6.git - fetch = +refs/heads/*:refs/remotes/linux-nfs/* +[remote "staging"] + url = git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/staging.git + fetch = +refs/heads/*:refs/remotes/staging/* ... ------------------------------------------------- @@ -1835,7 +1841,7 @@ Once the index is updated with the results of the conflict resolution, instead of creating a new commit, just run ------------------------------------------------- -$ git am --resolved +$ git am --continue ------------------------------------------------- and Git will create the commit for you and continue applying the @@ -2156,7 +2162,7 @@ To set this up, first create your work tree by cloning Linus's public tree: ------------------------------------------------- -$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git work +$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git work $ cd work ------------------------------------------------- @@ -2198,7 +2204,7 @@ make it easy to push both branches to your public tree. (See ------------------------------------------------- $ cat >> .git/config <<EOF [remote "mytree"] - url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux-2.6.git + url = master.kernel.org:/pub/scm/linux/kernel/git/aegl/linux.git push = release push = test EOF @@ -4256,15 +4262,16 @@ no longer need to call `setup_pager()` directly). Nowadays, `git log` is a builtin, which means that it is _contained_ in the command `git`. The source side of a builtin is -- a function called `cmd_<bla>`, typically defined in `builtin-<bla>.c`, - and declared in `builtin.h`, +- a function called `cmd_<bla>`, typically defined in `builtin/<bla.c>` + (note that older versions of Git used to have it in `builtin-<bla>.c` + instead), and declared in `builtin.h`. - an entry in the `commands[]` array in `git.c`, and - an entry in `BUILTIN_OBJECTS` in the `Makefile`. Sometimes, more than one builtin is contained in one source file. For -example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin-log.c`, +example, `cmd_whatchanged()` and `cmd_log()` both reside in `builtin/log.c`, since they share quite a bit of code. In that case, the commands which are _not_ named like the `.c` file in which they live have to be listed in `BUILT_INS` in the `Makefile`. @@ -4287,10 +4294,10 @@ For the sake of clarity, let's stay with `git cat-file`, because it - is plumbing, and - was around even in the initial commit (it literally went only through - some 20 revisions as `cat-file.c`, was renamed to `builtin-cat-file.c` + some 20 revisions as `cat-file.c`, was renamed to `builtin/cat-file.c` when made a builtin, and then saw less than 10 versions). -So, look into `builtin-cat-file.c`, search for `cmd_cat_file()` and look what +So, look into `builtin/cat-file.c`, search for `cmd_cat_file()` and look what it does. ------------------------------------------------------------------ @@ -4366,7 +4373,7 @@ Another example: Find out what to do in order to make some script a builtin: ------------------------------------------------- -$ git log --no-merges --diff-filter=A builtin-*.c +$ git log --no-merges --diff-filter=A builtin/*.c ------------------------------------------------- You see, Git is actually the best tool to find out about the source of Git |