diff options
Diffstat (limited to 'Documentation')
46 files changed, 454 insertions, 137 deletions
diff --git a/Documentation/Makefile b/Documentation/Makefile index a4c4063e50..e117bc4315 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -279,7 +279,7 @@ $(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt XSLT = docbook.xsl XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css -user-manual.html: user-manual.xml +user-manual.html: user-manual.xml $(XSLT) $(QUIET_XSLTPROC)$(RM) $@+ $@ && \ xsltproc $(XSLTOPTS) -o $@+ $(XSLT) $< && \ mv $@+ $@ diff --git a/Documentation/RelNotes-1.7.2.3.txt b/Documentation/RelNotes-1.7.2.3.txt new file mode 100644 index 0000000000..610960cfe1 --- /dev/null +++ b/Documentation/RelNotes-1.7.2.3.txt @@ -0,0 +1,39 @@ +Git v1.7.2.3 Release Notes +========================== + +Fixes since v1.7.2.2 +-------------------- + + * When people try insane things such as delta-compressing 4GiB files, we + threw an assertion failure. + + * "git archive" gave the full commit ID for "$Format:%h$". + + * "git fetch --tags" did not fetch tags when remote.<nick>.tagopt was set + to --no-tags. The command line option now overrides the configuration + setting. + + * "git for-each-ref --format='%(objectname:short)'" has been completely + broken for a long time. + + * "git gc" incorrectly pruned a rerere record that was created long + time ago but still is actively and repeatedly used. + + * "git log --follow -M -p" was seriously broken in 1.7.2, reporting + assertion failure. + + * Running "git log" with an incorrect option started pager nevertheless, + forcing the user to dismiss it. + + * "git rebase" did not work well when the user has diff.renames + configuration variable set. + + * An earlier (and rather old) fix to "git rebase" against a rebased + upstream broke a more normal, non rebased upstream case rather badly, + attempting to re-apply patches that are already accepted upstream. + + * "git submodule sync" forgot to update the superproject's config file + when submodule URL changed. + + * "git pack-refs --all --prune" did not remove a directory that has + become empty. diff --git a/Documentation/RelNotes-1.7.3.txt b/Documentation/RelNotes-1.7.3.txt new file mode 100644 index 0000000000..3512bbb238 --- /dev/null +++ b/Documentation/RelNotes-1.7.3.txt @@ -0,0 +1,73 @@ +Git v1.7.3 Release Notes (draft) +================================ + +Updates since v1.7.2 +-------------------- + + * git-gui got various updates and a new maintainer, Pat Thoyts. + + * Gitweb allows its configuration to change per each request; it used to + read the configuration once upon startup. + + * When git finds a corrupt object, it now reports the file that contains + it. + + * "git checkout -B <it>" is a shorter way to say "git branch -f <it>" + followed by "git checkout <it>". + + * When "git checkout" or "git merge" refuse to proceed in order to + protect local modification to your working tree, they used to stop + after showing just one path that might be lost. They now show all, + in a format that is easier to read. + + * "git clean" learned "-e" ("--exclude") option. + + * Hunk headers produced for C# files by "git diff" and friends show more + relevant context than before. + + * diff.ignoresubmodules configuration variable can be used to squelch the + differences in submodules reported when running commands (e.g. "diff", + "status", etc.) at the superproject level. + + * http.useragent configuration can be used to lie who you are to your + restrictive firewall. + + * "git rebase --strategy <s>" learned "-X" option to pass extra options + that are understood by the chosen merge strategy. + + * "git rebase -i" learned "exec" that you can insert into the insn sheet + to run a command between its steps. + + * "git rebase" between branches that have many binary changes that do + not conflict should be faster. + + * "git rebase -i" peeks into rebase.autosquash configuration and acts as + if you gave --autosquash from the command line. + + +Also contains various documentation updates. + + +Fixes since v1.7.2 +------------------ + +All of the fixes in v1.7.2.X maintenance series are included in this +release, unless otherwise noted. + + * "git merge -s recursive" (which is the default) did not handle cases + where a directory becomes a file (or vice versa) very well. + + * "git fetch" and friends were accidentally broken for url with "+" in + its path, e.g. "git://git.gnome.org/gtk+". + +--- +exec >/var/tmp/1 +echo O=$(git describe master) +O=v1.7.2.2-268-g7e42332 +O=v1.7.2 +git shortlog --no-merges $O..master ^maint +exit 0 + +What did we want to do with... + +1e3d411 (Enable custom schemes for column colors in the graph API, 2010-07-13) diff --git a/Documentation/asciidoc.conf b/Documentation/asciidoc.conf index 87a90f2c3f..aea8627be0 100644 --- a/Documentation/asciidoc.conf +++ b/Documentation/asciidoc.conf @@ -16,8 +16,11 @@ plus=+ caret=^ startsb=[ endsb=] +backslash=\ tilde=~ +apostrophe=' backtick=` +litdd=-- ifdef::backend-docbook[] [linkgit-inlinemacro] diff --git a/Documentation/config.txt b/Documentation/config.txt index 05ec3fed89..d294dd6dcd 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -450,6 +450,15 @@ core.excludesfile:: to the value of `$HOME` and "{tilde}user/" to the specified user's home directory. See linkgit:gitignore[5]. +core.askpass:: + Some commands (e.g. svn and http interfaces) that interactively + ask for a password can be told to use an external program given + via the value of this variable. Can be overridden by the 'GIT_ASKPASS' + environment variable. If not set, fall back to the value of the + 'SSH_ASKPASS' environment variable or, failing that, a simple password + prompt. The external program shall be given a suitable prompt as + command line argument and write the password on its STDOUT. + core.editor:: Commands such as `commit` and `tag` that lets you edit messages by launching an editor uses the value of this @@ -829,7 +838,8 @@ diff.renames:: diff.ignoreSubmodules:: Sets the default value of --ignore-submodules. Note that this affects only 'git diff' Porcelain, and not lower level 'diff' - commands such as 'git diff-files'. + commands such as 'git diff-files'. 'git checkout' also honors + this setting when reporting uncommitted changes. diff.suppressBlankEmpty:: A boolean to inhibit the standard behavior of printing a space @@ -1305,10 +1315,11 @@ interactive.singlekey:: ignored if portable keystroke input is not available. log.date:: - Set default date-time mode for the log command. Setting log.date - value is similar to using 'git log'\'s --date option. The value is one of the - following alternatives: {relative,local,default,iso,rfc,short}. - See linkgit:git-log[1]. + Set the default date-time mode for the 'log' command. + Setting a value for log.date is similar to using 'git log''s + `\--date` option. Possible values are `relative`, `local`, + `default`, `iso`, `rfc`, and `short`; see linkgit:git-log[1] + for details. log.decorate:: Print out the ref names of any commits that are shown by the log @@ -1549,6 +1560,9 @@ rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. +rebase.autosquash:: + If set to true enable '--autosquash' option by default. + receive.autogc:: By default, git-receive-pack will run "git-gc --auto" after receiving data from git-push and updating refs. You can stop @@ -1643,7 +1657,9 @@ remote.<name>.tagopt:: Setting this value to \--no-tags disables automatic tag following when fetching from remote <name>. Setting it to \--tags will fetch every tag from remote <name>, even if they are not reachable from remote - branch heads. + branch heads. Passing these flags directly to linkgit:git-fetch[1] can + override this setting. See options \--tags and \--no-tags of + linkgit:git-fetch[1]. remote.<name>.vcs:: Setting this to a value <vcs> will cause git to interact with diff --git a/Documentation/docbook.xsl b/Documentation/docbook.xsl index 9a6912c641..da8b05b922 100644 --- a/Documentation/docbook.xsl +++ b/Documentation/docbook.xsl @@ -1,5 +1,8 @@ <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'> <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/> - <xsl:output method="html" encoding="UTF-8" indent="no" /> + <xsl:output method="html" + encoding="UTF-8" indent="no" + doctype-public="-//W3C//DTD HTML 4.01//EN" + doctype-system="http://www.w3.org/TR/html4/strict.dtd" /> </xsl:stylesheet> diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 9333c42c55..470ac31396 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -49,7 +49,9 @@ ifndef::git-pull[] endif::git-pull[] By default, tags that point at objects that are downloaded from the remote repository are fetched and stored locally. - This option disables this automatic tag following. + This option disables this automatic tag following. The default + behavior for a remote may be specified with the remote.<name>.tagopt + setting. See linkgit:git-config[1]. -t:: --tags:: @@ -58,7 +60,9 @@ endif::git-pull[] objects reachable from the branch heads that are being tracked will not be fetched by this mechanism. This flag lets all tags and their associated objects be - downloaded. + downloaded. The default behavior for a remote may be + specified with the remote.<name>.tagopt setting. See + linkgit:git-config[1]. -u:: --update-head-ok:: diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index e22a62f065..73378b2bef 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -157,14 +157,14 @@ those in info/exclude. See linkgit:gitrepository-layout[5]. EXAMPLES -------- -* Adds content from all `\*.txt` files under `Documentation` directory +* Adds content from all `*.txt` files under `Documentation` directory and its subdirectories: + ------------ $ git add Documentation/\*.txt ------------ + -Note that the asterisk `\*` is quoted from the shell in this +Note that the asterisk `*` is quoted from the shell in this example; this lets the command include the files from subdirectories of `Documentation/` directory. @@ -220,7 +220,7 @@ binary so line count cannot be shown) and there is no difference between indexed copy and the working tree version (if the working tree version were also different, 'binary' would have been shown in place of 'nothing'). The -other file, git-add--interactive.perl, has 403 lines added +other file, git-add{litdd}interactive.perl, has 403 lines added and 35 lines deleted if you commit what is in the index, but working tree file has further modifications (one addition and one deletion). diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index 4d4325f222..4f358c8d6c 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -44,7 +44,7 @@ archives that it imports, it is also possible to specify git branch names manually. To do so, write a git branch name after each <archive/branch> parameter, separated by a colon. This way, you can shorten the Arch branch names and convert Arch jargon to git jargon, for example mapping a -"PROJECT--devo--VERSION" branch to "master". +"PROJECT{litdd}devo{litdd}VERSION" branch to "master". Associating multiple Arch branches to one git branch is possible; the result will make the most sense only if no commits are made to the first @@ -85,8 +85,8 @@ OPTIONS -o:: Use this for compatibility with old-style branch names used by earlier versions of 'git archimport'. Old-style branch names - were category--branch, whereas new-style branch names are - archive,category--branch--version. In both cases, names given + were category{litdd}branch, whereas new-style branch names are + archive,category{litdd}branch{litdd}version. In both cases, names given on the command-line will override the automatically-generated ones. diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index efbe3790bb..8a2ba37904 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -873,7 +873,7 @@ c * N * T + b * M * log2(M) tests where c is the number of rounds of test (so a small constant) and b is the ratio of bug per commit (hopefully a small constant too). -So of course it's much better as it's O(N \* T) vs O(N \* T \* M) if +So of course it's much better as it's O(N * T) vs O(N * T * M) if you would test everything after each commit. This means that test suites are good to prevent some bugs from being diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index a5ed8fb05b..38e59afb34 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -9,7 +9,7 @@ git-bundle - Move objects and refs by archive SYNOPSIS -------- [verse] -'git bundle' create <file> <git-rev-list args> +'git bundle' create <file> <git-rev-list-args> 'git bundle' verify <file> 'git bundle' list-heads <file> [refname...] 'git bundle' unbundle <file> [refname...] @@ -34,57 +34,58 @@ OPTIONS ------- create <file>:: - Used to create a bundle named 'file'. This requires the - 'git rev-list' arguments to define the bundle contents. + Used to create a bundle named 'file'. This requires the + 'git-rev-list-args' arguments to define the bundle contents. verify <file>:: - Used to check that a bundle file is valid and will apply - cleanly to the current repository. This includes checks on the - bundle format itself as well as checking that the prerequisite - commits exist and are fully linked in the current repository. - 'git bundle' prints a list of missing commits, if any, and exits - with a non-zero status. + Used to check that a bundle file is valid and will apply + cleanly to the current repository. This includes checks on the + bundle format itself as well as checking that the prerequisite + commits exist and are fully linked in the current repository. + 'git bundle' prints a list of missing commits, if any, and exits + with a non-zero status. list-heads <file>:: - Lists the references defined in the bundle. If followed by a - list of references, only references matching those given are - printed out. + Lists the references defined in the bundle. If followed by a + list of references, only references matching those given are + printed out. unbundle <file>:: - Passes the objects in the bundle to 'git index-pack' - for storage in the repository, then prints the names of all - defined references. If a list of references is given, only - references matching those in the list are printed. This command is - really plumbing, intended to be called only by 'git fetch'. - -[git-rev-list-args...]:: - A list of arguments, acceptable to 'git rev-parse' and - 'git rev-list', that specifies the specific objects and references - to transport. For example, `master\~10..master` causes the - current master reference to be packaged along with all objects - added since its 10th ancestor commit. There is no explicit - limit to the number of references and objects that may be - packaged. + Passes the objects in the bundle to 'git index-pack' + for storage in the repository, then prints the names of all + defined references. If a list of references is given, only + references matching those in the list are printed. This command is + really plumbing, intended to be called only by 'git fetch'. + +<git-rev-list-args>:: + A list of arguments, acceptable to 'git rev-parse' and + 'git rev-list' (and containg a named ref, see SPECIFYING REFERENCES + below), that specifies the specific objects and references + to transport. For example, `master{tilde}10..master` causes the + current master reference to be packaged along with all objects + added since its 10th ancestor commit. There is no explicit + limit to the number of references and objects that may be + packaged. [refname...]:: - A list of references used to limit the references reported as - available. This is principally of use to 'git fetch', which - expects to receive only those references asked for and not - necessarily everything in the pack (in this case, 'git bundle' acts - like 'git fetch-pack'). + A list of references used to limit the references reported as + available. This is principally of use to 'git fetch', which + expects to receive only those references asked for and not + necessarily everything in the pack (in this case, 'git bundle' acts + like 'git fetch-pack'). SPECIFYING REFERENCES --------------------- 'git bundle' will only package references that are shown by 'git show-ref': this includes heads, tags, and remote heads. References -such as `master\~1` cannot be packaged, but are perfectly suitable for +such as `master{tilde}1` cannot be packaged, but are perfectly suitable for defining the basis. More than one reference may be packaged, and more than one basis can be specified. The objects packaged are those not contained in the union of the given bases. Each basis can be -specified explicitly (e.g. `^master\~10`), or implicitly (e.g. -`master\~10..master`, `--since=10.days.ago master`). +specified explicitly (e.g. `^master{tilde}10`), or implicitly (e.g. +`master{tilde}10..master`, `--since=10.days.ago master`). It is very important that the basis used be held by the destination. It is okay to err on the side of caution, causing the bundle file @@ -154,7 +155,7 @@ machineB$ git pull If you know up to what commit the intended recipient repository should have the necessary objects, you can use that knowledge to specify the basis, giving a cut-off point to limit the revisions and objects that go -in the resulting bundle. The previous example used lastR2bundle tag +in the resulting bundle. The previous example used the lastR2bundle tag for this purpose, but you can use any other options that you would give to the linkgit:git-log[1] command. Here are more examples: @@ -194,7 +195,7 @@ references when fetching: $ git fetch mybundle master:localRef ---------------- -You can also see what references it offers. +You can also see what references it offers: ---------------- $ git ls-remote mybundle diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index d6aa6e14eb..62f9ab24c9 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -13,7 +13,7 @@ SYNOPSIS [--stage=<number>|all] [--temp] [-z] [--stdin] - [--] [<file>]\* + [--] [<file>]* DESCRIPTION ----------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 66e570113a..f88e9977d1 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -187,7 +187,7 @@ As a special case, the `"@\{-N\}"` syntax for the N-th last branch checks out the branch (instead of detaching). You may also specify `-` which is synonymous with `"@\{-1\}"`. + -As a further special case, you may use `"A...B"` as a shortcut for the +As a further special case, you may use `"A\...B"` as a shortcut for the merge base of `A` and `B` if there is exactly one merge base. You can leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index 61888547a1..349366ee1e 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -8,7 +8,7 @@ git-commit-tree - Create a new commit object SYNOPSIS -------- -'git commit-tree' <tree> [-p <parent commit>]\* < changelog +'git commit-tree' <tree> [-p <parent commit>]* < changelog DESCRIPTION ----------- diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 98ec6b5871..fcad113276 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -90,10 +90,16 @@ marks the same across runs. resulting stream can only be used by a repository which already contains the necessary objects. +--full-tree:: + This option will cause fast-export to issue a "deleteall" + directive for each commit followed by a full list of all files + in the commit (as opposed to just listing the files which are + different from the commit's first parent). + [git-rev-list-args...]:: A list of arguments, acceptable to 'git rev-parse' and 'git rev-list', that specifies the specific objects and references - to export. For example, `master\~10..master` causes the + to export. For example, `master{tilde}10..master` causes the current master reference to be exported along with all objects added since its 10th ancestor commit. diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index a585dbe898..302f56b889 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -9,8 +9,8 @@ git-fmt-merge-msg - Produce a merge commit message SYNOPSIS -------- [verse] -'git fmt-merge-msg' [--log | --no-log] <$GIT_DIR/FETCH_HEAD -'git fmt-merge-msg' [--log | --no-log] -F <file> +'git fmt-merge-msg' [-m <message>] [--log | --no-log] <$GIT_DIR/FETCH_HEAD +'git fmt-merge-msg' [-m <message>] [--log | --no-log] -F <file> DESCRIPTION ----------- @@ -38,6 +38,11 @@ OPTIONS Synonyms to --log and --no-log; these are deprecated and will be removed in the future. +-m <message>:: +--message <message>:: + Use <message> instead of the branch names for the first line + of the log message. For use with `--log`. + -F <file>:: --file <file>:: Take the list of merged objects from <file> instead of diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 390d85ccae..d66fd9d231 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] - [--sort=<key>]\* [--format=<format>] [<pattern>...] + [--sort=<key>]* [--format=<format>] [<pattern>...] DESCRIPTION ----------- diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 5474dd7f94..dab0a78fa8 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -191,11 +191,11 @@ OPTIONS Examples -------- -git grep 'time_t' \-- '*.[ch]':: +git grep {apostrophe}time_t{apostrophe} \-- {apostrophe}*.[ch]{apostrophe}:: Looks for `time_t` in all tracked .c and .h files in the working directory and its subdirectories. -git grep -e \'#define\' --and \( -e MAX_PATH -e PATH_MAX \):: +git grep -e {apostrophe}#define{apostrophe} --and \( -e MAX_PATH -e PATH_MAX \):: Looks for a line that has `#define` and either `MAX_PATH` or `PATH_MAX`. diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index f8df109d07..eccd0ffd38 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -55,9 +55,9 @@ other display programs (see below). + The web browser can be specified using the configuration variable 'help.browser', or 'web.browser' if the former is not set. If none of -these config variables is set, the 'git web--browse' helper script +these config variables is set, the 'git web{litdd}browse' helper script (called by 'git help') will pick a suitable default. See -linkgit:git-web--browse[1] for more information about this. +linkgit:git-web{litdd}browse[1] for more information about this. CONFIGURATION VARIABLES ----------------------- @@ -80,7 +80,7 @@ help.browser, web.browser and browser.<tool>.path The 'help.browser', 'web.browser' and 'browser.<tool>.path' will also be checked if the 'web' format is chosen (either by command line option or configuration variable). See '-w|--web' in the OPTIONS -section above and linkgit:git-web--browse[1]. +section above and linkgit:git-web{litdd}browse[1]. man.viewer ~~~~~~~~~~ diff --git a/Documentation/git-instaweb.txt b/Documentation/git-instaweb.txt index e70cea9320..7477ce8fa8 100644 --- a/Documentation/git-instaweb.txt +++ b/Documentation/git-instaweb.txt @@ -44,9 +44,9 @@ OPTIONS -b:: --browser:: The web browser that should be used to view the gitweb - page. This will be passed to the 'git web--browse' helper + page. This will be passed to the 'git web{litdd}browse' helper script along with the URL of the gitweb instance. See - linkgit:git-web--browse[1] for more information about this. If + linkgit:git-web{litdd}browse[1] for more information about this. If the script fails, the URL will be printed to stdout. start:: @@ -82,7 +82,7 @@ You may specify configuration in your .git/config If the configuration variable 'instaweb.browser' is not set, 'web.browser' will be used instead if it is defined. See -linkgit:git-web--browse[1] for more information about this. +linkgit:git-web{litdd}browse[1] for more information about this. Author ------ diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index a7c8174d01..15aee2f953 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -10,14 +10,14 @@ SYNOPSIS -------- [verse] 'git ls-files' [-z] [-t] [-v] - (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])\* - (-[c|d|o|i|s|u|k|m])\* + (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])* + (-[c|d|o|i|s|u|k|m])* [-x <pattern>|--exclude=<pattern>] [-X <file>|--exclude-from=<file>] [--exclude-per-directory=<file>] [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] - [--full-name] [--abbrev] [--] [<file>]\* + [--full-name] [--abbrev] [--] [<file>]* DESCRIPTION ----------- diff --git a/Documentation/git-merge-base.txt b/Documentation/git-merge-base.txt index ce5b369985..eedef1bb1a 100644 --- a/Documentation/git-merge-base.txt +++ b/Documentation/git-merge-base.txt @@ -8,7 +8,9 @@ git-merge-base - Find as good common ancestors as possible for a merge SYNOPSIS -------- -'git merge-base' [-a|--all] <commit> <commit>... +[verse] +'git merge-base' [-a|--all] [--octopus] <commit> <commit>... +'git merge-base' --independent <commit>... DESCRIPTION ----------- @@ -20,12 +22,12 @@ that does not have any better common ancestor is a 'best common ancestor', i.e. a 'merge base'. Note that there can be more than one merge base for a pair of commits. -Among the two commits to compute the merge base from, one is specified by -the first commit argument on the command line; the other commit is a -(possibly hypothetical) commit that is a merge across all the remaining -commits on the command line. As the most common special case, specifying only -two commits on the command line means computing the merge base between -the given two commits. +Unless `--octopus` is given, among the two commits to compute the merge +base from, one is specified by the first commit argument on the command +line; the other commit is a (possibly hypothetical) commit that is a merge +across all the remaining commits on the command line. As the most common +special case, specifying only two commits on the command line means +computing the merge base between the given two commits. As a consequence, the 'merge base' is not necessarily contained in each of the commit arguments if more than two commits are specified. This is different @@ -37,6 +39,18 @@ OPTIONS --all:: Output all merge bases for the commits, instead of just one. +--octopus:: + Compute the best common ancestors of all supplied commits, + in preparation for an n-way merge. This mimics the behavior + of 'git show-branch --merge-base'. + +--independent:: + Instead of printing merge bases, print a minimal subset of + the supplied commits with the same ancestors. In other words, + among the commits given, list those which cannot be reached + from any other. This mimics the behavior of 'git show-branch + --independent'. + DISCUSSION ---------- @@ -96,6 +110,12 @@ Documentation -------------- Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. +See also +-------- +linkgit:git-rev-list[1], +linkgit:git-show-branch[1], +linkgit:git-merge[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-merge-index.txt b/Documentation/git-merge-index.txt index 4d266de9cc..921b38f183 100644 --- a/Documentation/git-merge-index.txt +++ b/Documentation/git-merge-index.txt @@ -8,7 +8,7 @@ git-merge-index - Run a merge for files needing merging SYNOPSIS -------- -'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>\*) +'git merge-index' [-o] [-q] <merge-program> (-a | [--] <file>*) DESCRIPTION ----------- diff --git a/Documentation/git-mergetool--lib.txt b/Documentation/git-mergetool--lib.txt index 78eb03f0ae..d8df55362c 100644 --- a/Documentation/git-mergetool--lib.txt +++ b/Documentation/git-mergetool--lib.txt @@ -1,5 +1,5 @@ -git-mergetool--lib(1) -===================== +git-mergetool{litdd}lib(1) +========================== NAME ---- @@ -16,11 +16,11 @@ This is not a command the end user would want to run. Ever. This documentation is meant for people who are studying the Porcelain-ish scripts and/or are writing new ones. -The 'git-mergetool--lib' scriptlet is designed to be sourced (using +The 'git-mergetool{litdd}lib' scriptlet is designed to be sourced (using `.`) by other shell scripts to set up functions for working with git merge tools. -Before sourcing 'git-mergetool--lib', your script must set `TOOL_MODE` +Before sourcing 'git-mergetool{litdd}lib', your script must set `TOOL_MODE` to define the operation mode for the functions listed below. 'diff' and 'merge' are valid values. diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index 658ff2ff67..020955ff5a 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -200,7 +200,7 @@ summary:: For a successfully pushed ref, the summary shows the old and new values of the ref in a form suitable for using as an argument to `git log` (this is `<old>..<new>` in most cases, and - `<old>...<new>` for forced non-fast-forward updates). + `<old>\...<new>` for forced non-fast-forward updates). + For a failed update, more details are given: + diff --git a/Documentation/git-rebase.txt b/Documentation/git-rebase.txt index 3b87f1a1b6..30e5c0eb14 100644 --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@ -199,6 +199,9 @@ rebase.stat:: Whether to show a diffstat of what changed upstream since the last rebase. False by default. +rebase.autosquash:: + If set to true enable '--autosquash' option by default. + OPTIONS ------- <newbase>:: @@ -207,7 +210,7 @@ OPTIONS <upstream>. May be any valid commit, and not just an existing branch name. + -As a special case, you may use "A...B" as a shortcut for the +As a special case, you may use "A\...B" as a shortcut for the merge base of A and B if there is exactly one merge base. You can leave out at most one of A and B, in which case it defaults to HEAD. @@ -333,6 +336,7 @@ idea unless you know what you are doing (see BUGS below). instead. --autosquash:: +--no-autosquash:: When the commit log message begins with "squash! ..." (or "fixup! ..."), and there is a commit whose title begins with the same ..., automatically modify the todo list of rebase -i @@ -341,6 +345,10 @@ idea unless you know what you are doing (see BUGS below). commit from `pick` to `squash` (or `fixup`). + This option is only valid when the '--interactive' option is used. ++ +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-ff:: With --interactive, cherry-pick all rebased commits instead of diff --git a/Documentation/git-relink.txt b/Documentation/git-relink.txt index 25ff8f9dcb..8a5842bb93 100644 --- a/Documentation/git-relink.txt +++ b/Documentation/git-relink.txt @@ -7,7 +7,7 @@ git-relink - Hardlink common objects in local repositories SYNOPSIS -------- -'git relink' [--safe] <dir> [<dir>]\* <master_dir> +'git relink' [--safe] <dir> [<dir>]* <master_dir> DESCRIPTION ----------- diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index be4c053360..341ca90c6e 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -74,7 +74,7 @@ OPTIONS properly quoted for consumption by shell. Useful when you expect your parameter to contain whitespaces and newlines (e.g. when using pickaxe `-S` with - 'git diff-\*'). In contrast to the `--sq-quote` option, + 'git diff-{asterisk}'). In contrast to the `--sq-quote` option, the command input is still interpreted as usual. --not:: @@ -112,14 +112,15 @@ OPTIONS + If a `pattern` is given, only refs matching the given shell glob are shown. If the pattern does not contain a globbing character (`?`, -`\*`, or `[`), it is turned into a prefix match by appending `/\*`. +`{asterisk}`, or `[`), it is turned into a prefix match by +appending `/{asterisk}`. --glob=pattern:: Show all refs matching the shell glob pattern `pattern`. If the pattern does not start with `refs/`, this is automatically prepended. If the pattern does not contain a globbing - character (`?`, `\*`, or `[`), it is turned into a prefix - match by appending `/\*`. + character (`?`, `{asterisk}`, or `[`), it is turned into a prefix + match by appending `/{asterisk}`. --show-toplevel:: Show the absolute path of the top-level directory. diff --git a/Documentation/git-rm.txt b/Documentation/git-rm.txt index c21d19e573..71e3d9fc23 100644 --- a/Documentation/git-rm.txt +++ b/Documentation/git-rm.txt @@ -78,7 +78,8 @@ a file that you have not told git about does not remove that file. File globbing matches across directory boundaries. Thus, given two directories `d` and `d2`, there is a difference between -using `git rm \'d\*\'` and `git rm \'d/\*\'`, as the former will +using `git rm {apostrophe}d{asterisk}{apostrophe}` and +`git rm {apostrophe}d/{asterisk}{apostrophe}`, as the former will also remove all of directory `d2`. REMOVING FILES THAT HAVE DISAPPEARED FROM THE FILESYSTEM @@ -135,11 +136,11 @@ git diff --name-only --diff-filter=D -z | xargs -0 git rm --cached EXAMPLES -------- -git rm Documentation/\\*.txt:: - Removes all `\*.txt` files from the index that are under the +git rm Documentation/\*.txt:: + Removes all `*.txt` files from the index that are under the `Documentation` directory and any of its subdirectories. + -Note that the asterisk `\*` is quoted from the shell in this +Note that the asterisk `*` is quoted from the shell in this example; this lets git, and not the shell, expand the pathnames of files and subdirectories under the `Documentation/` directory. diff --git a/Documentation/git-show-branch.txt b/Documentation/git-show-branch.txt index 81ba29669c..6453263340 100644 --- a/Documentation/git-show-branch.txt +++ b/Documentation/git-show-branch.txt @@ -168,10 +168,10 @@ $ git show-branch master fixes mhf ------------------------------------------------ These three branches all forked from a common commit, [master], -whose commit message is "Add \'git show-branch\'". The "fixes" -branch adds one commit "Introduce "reset type" flag to "git reset"". -The "mhf" branch adds many other commits. The current branch -is "master". +whose commit message is "Add {apostrophe}git show-branch{apostrophe}". +The "fixes" branch adds one commit "Introduce "reset type" flag to +"git reset"". The "mhf" branch adds many other commits. +The current branch is "master". EXAMPLE diff --git a/Documentation/git-show-ref.txt b/Documentation/git-show-ref.txt index 75780d7d63..4696af7433 100644 --- a/Documentation/git-show-ref.txt +++ b/Documentation/git-show-ref.txt @@ -73,8 +73,8 @@ OPTIONS --exclude-existing[=<pattern>]:: Make 'git show-ref' act as a filter that reads refs from stdin of the - form "^(?:<anything>\s)?<refname>(?:\^\{\})?$" and performs the - following actions on each: + form "^(?:<anything>\s)?<refname>(?:{backslash}{caret}\{\})?$" + and performs the following actions on each: (1) strip "^{}" at the end of line if any; (2) ignore if pattern is provided and does not head-match refname; (3) warn if refname is not a well-formed refname and skip; diff --git a/Documentation/git-stash.txt b/Documentation/git-stash.txt index 473889a660..8728f7a514 100644 --- a/Documentation/git-stash.txt +++ b/Documentation/git-stash.txt @@ -104,18 +104,22 @@ tree's changes, but also the index's ones. However, this can fail, when you have conflicts (which are stored in the index, where you therefore can no longer apply the changes as they were originally). + -When no `<stash>` is given, `stash@\{0}` is assumed. +When no `<stash>` is given, `stash@\{0}` is assumed, otherwise `<stash>` must +be a reference of the form `stash@\{<revision>}`. apply [--index] [-q|--quiet] [<stash>]:: - Like `pop`, but do not remove the state from the stash list. + Like `pop`, but do not remove the state from the stash list. Unlike `pop`, + `<stash>` may be any commit that looks like a commit created by + `stash save` or `stash create`. branch <branchname> [<stash>]:: Creates and checks out a new branch named `<branchname>` starting from the commit at which the `<stash>` was originally created, applies the - changes recorded in `<stash>` to the new working tree and index, then - drops the `<stash>` if that completes successfully. When no `<stash>` + changes recorded in `<stash>` to the new working tree and index. + If that succeeds, and `<stash>` is a reference of the form + `stash@{<revision>}`, it then drops the `<stash>`. When no `<stash>` is given, applies the latest one. + This is useful if the branch on which you ran `git stash save` has @@ -132,7 +136,9 @@ clear:: drop [-q|--quiet] [<stash>]:: Remove a single stashed state from the stash list. When no `<stash>` - is given, it removes the latest one. i.e. `stash@\{0}` + is given, it removes the latest one. i.e. `stash@\{0}`, otherwise + `<stash>` must a valid stash log reference of the form + `stash@\{<revision>}`. create:: diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt index 765d4b312e..74d1d49dbf 100644 --- a/Documentation/git-update-index.txt +++ b/Documentation/git-update-index.txt @@ -12,7 +12,7 @@ SYNOPSIS 'git update-index' [--add] [--remove | --force-remove] [--replace] [--refresh] [-q] [--unmerged] [--ignore-missing] - [--cacheinfo <mode> <object> <file>]\* + [--cacheinfo <mode> <object> <file>]* [--chmod=(+|-)x] [--assume-unchanged | --no-assume-unchanged] [--skip-worktree | --no-skip-worktree] @@ -21,7 +21,7 @@ SYNOPSIS [--info-only] [--index-info] [-z] [--stdin] [--verbose] - [--] [<file>]\* + [--] [<file>]* DESCRIPTION ----------- diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 75720491b2..e1586c78c3 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -1,5 +1,5 @@ -git-web--browse(1) -================== +git-web{litdd}browse(1) +======================= NAME ---- @@ -7,7 +7,7 @@ git-web--browse - git helper script to launch a web browser SYNOPSIS -------- -'git web--browse' [OPTIONS] URL/FILE ... +'git web{litdd}browse' [OPTIONS] URL/FILE ... DESCRIPTION ----------- @@ -71,7 +71,7 @@ browser.<tool>.cmd When the browser, specified by options or configuration variables, is not among the supported ones, then the corresponding 'browser.<tool>.cmd' configuration variable will be looked up. If this -variable exists then 'git web--browse' will treat the specified tool +variable exists then 'git web{litdd}browse' will treat the specified tool as a custom command and will use a shell eval to run the command with the URLs passed as arguments. diff --git a/Documentation/git.txt b/Documentation/git.txt index 531789321c..e341075078 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -44,9 +44,10 @@ unreleased) version of git, that is available from 'master' branch of the `git.git` repository. Documentation for older releases are available here: -* link:v1.7.2.2/git.html[documentation for release 1.7.2.2] +* link:v1.7.2.3/git.html[documentation for release 1.7.2.3] * release notes for + link:RelNotes-1.7.2.3.txt[1.7.2.3], link:RelNotes-1.7.2.2.txt[1.7.2.2], link:RelNotes-1.7.2.1.txt[1.7.2.1], link:RelNotes-1.7.2.txt[1.7.2]. @@ -638,6 +639,13 @@ Usually it is easier to configure any desired options through your personal `.ssh/config` file. Please consult your ssh documentation for further details. +'GIT_ASKPASS':: + If this environment variable is set, then git commands which need to + acquire passwords or passphrases (e.g. for HTTP or IMAP authentication) + will call this program with a suitable prompt as command line argument + and read the password from its STDOUT. See also the 'core.askpass' + option in linkgit:git-config[1]. + 'GIT_FLUSH':: If this environment variable is set to "1", then commands such as 'git blame' (in incremental mode), 'git rev-list', 'git log', diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index 2e2370ccdb..e5a27d875e 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -317,6 +317,17 @@ command is "cat"). smudge = cat ------------------------ +For best results, `clean` should not alter its output further if it is +run twice ("clean->clean" should be equivalent to "clean"), and +multiple `smudge` commands should not alter `clean`'s output +("smudge->smudge->clean" should be equivalent to "clean"). See the +section on merging below. + +The "indent" filter is well-behaved in this regard: it will not modify +input that is already correctly indented. In this case, the lack of a +smudge filter means that the clean filter _must_ accept its own output +without modifying it. + Interaction between checkin/checkout attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -331,6 +342,29 @@ In the check-out codepath, the blob content is first converted with `text`, and then `ident` and fed to `filter`. +Merging branches with differing checkin/checkout attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you have added attributes to a file that cause the canonical +repository format for that file to change, such as adding a +clean/smudge filter or text/eol/ident attributes, merging anything +where the attribute is not in place would normally cause merge +conflicts. + +To prevent these unnecessary merge conflicts, git can be told to run a +virtual check-out and check-in of all three stages of a file when +resolving a three-way merge by setting the `merge.renormalize` +configuration variable. This prevents changes caused by check-in +conversion from causing spurious merge conflicts when a converted file +is merged with an unconverted file. + +As long as a "smudge->clean" results in the same output as a "clean" +even on files that are already smudged, this strategy will +automatically resolve all filter-related conflicts. Filters that do +not act in this way may cause additional merge conflicts that must be +resolved manually. + + Generating diff text ~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gitcore-tutorial.txt b/Documentation/gitcore-tutorial.txt index ed3ddc92cb..5e9c5ebba3 100644 --- a/Documentation/gitcore-tutorial.txt +++ b/Documentation/gitcore-tutorial.txt @@ -110,7 +110,7 @@ An 'object' is identified by its 160-bit SHA1 hash, aka 'object name', and a reference to an object is always the 40-byte hex representation of that SHA1 name. The files in the `refs` subdirectory are expected to contain these hex references -(usually with a final `\'\n\'` at the end), and you should thus +(usually with a final `\n` at the end), and you should thus expect to see a number of 41-byte files containing these references in these `refs` subdirectories when you actually start populating your tree. @@ -310,7 +310,7 @@ and this will just output the name of the resulting tree, in this case ---------------- which is another incomprehensible object name. Again, if you want to, -you can use `git cat-file -t 8988d\...` to see that this time the object +you can use `git cat-file -t 8988d...` to see that this time the object is not a "blob" object, but a "tree" object (you can also use `git cat-file` to actually output the raw object contents, but you'll see mainly a binary mess, so that's less interesting). @@ -436,8 +436,8 @@ $ git update-index hello (note how we didn't need the `\--add` flag this time, since git knew about the file already). -Note what happens to the different 'git diff-\*' versions here. After -we've updated `hello` in the index, `git diff-files -p` now shows no +Note what happens to the different 'git diff-{asterisk}' versions here. +After we've updated `hello` in the index, `git diff-files -p` now shows no differences, but `git diff-index -p HEAD` still *does* show that the current state is different from the state we committed. In fact, now 'git diff-index' shows the same difference whether we use the `--cached` @@ -494,7 +494,7 @@ and it will show what the last commit (in `HEAD`) actually changed. [NOTE] ============ Here is an ASCII art by Jon Loeliger that illustrates how -various diff-\* commands compare things. +various 'diff-{asterisk}' commands compare things. diff-tree +----+ @@ -958,11 +958,11 @@ $ git show-branch --topo-order --more=1 master mybranch The first two lines indicate that it is showing the two branches and the first line of the commit log message from their top-of-the-tree commits, you are currently on `master` branch -(notice the asterisk `\*` character), and the first column for +(notice the asterisk `{asterisk}` character), and the first column for the later output lines is used to show commits contained in the `master` branch, and the second column for the `mybranch` branch. Three commits are shown along with their log messages. -All of them have non blank characters in the first column (`*` +All of them have non blank characters in the first column (`{asterisk}` shows an ordinary commit on the current branch, `-` is a merge commit), which means they are now part of the `master` branch. Only the "Some work" commit has the plus `+` character in the second column, @@ -1092,7 +1092,7 @@ Downloader from http and https URL first obtains the topmost commit object name from the remote site by looking at the specified refname under `repo.git/refs/` directory, and then tries to obtain the -commit object by downloading from `repo.git/objects/xx/xxx\...` +commit object by downloading from `repo.git/objects/xx/xxx...` using the object name of that commit object. Then it reads the commit object to find out its parent commits and the associate tree object; it repeats this process until it gets all the @@ -1420,7 +1420,7 @@ packed, and stores the packed file in `.git/objects/pack` directory. [NOTE] -You will see two files, `pack-\*.pack` and `pack-\*.idx`, +You will see two files, `pack-{asterisk}.pack` and `pack-{asterisk}.idx`, in `.git/objects/pack` directory. They are closely related to each other, and if you ever copy them by hand to a different repository for whatever reason, you should make sure you copy diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt index e10fa88b8c..7dc2e8b0bc 100644 --- a/Documentation/gitignore.txt +++ b/Documentation/gitignore.txt @@ -90,12 +90,12 @@ Patterns have the following format: - Otherwise, git treats the pattern as a shell glob suitable for consumption by fnmatch(3) with the FNM_PATHNAME flag: wildcards in the pattern will not match a / in the pathname. - For example, "Documentation/\*.html" matches + For example, "Documentation/{asterisk}.html" matches "Documentation/git.html" but not "Documentation/ppc/ppc.html" or "tools/perf/Documentation/perf.html". - A leading slash matches the beginning of the pathname. - For example, "/*.c" matches "cat-file.c" but not + For example, "/{asterisk}.c" matches "cat-file.c" but not "mozilla-sha1/sha1.c". An example: diff --git a/Documentation/howto/revert-branch-rebase.txt b/Documentation/howto/revert-branch-rebase.txt index 8c32da6deb..093c656048 100644 --- a/Documentation/howto/revert-branch-rebase.txt +++ b/Documentation/howto/revert-branch-rebase.txt @@ -112,25 +112,19 @@ $ git tag pu-anchor pu $ git rebase master * Applying: Redo "revert" using three-way merge machinery. First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: Remove git-apply-patch-script. First trying simple merge strategy to cherry-pick. Simple cherry-pick fails; trying Automatic cherry-pick. Removing Documentation/git-apply-patch-script.txt Removing git-apply-patch-script -Finished one cherry-pick. * Applying: Document "git cherry-pick" and "git revert" First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: mailinfo and applymbox updates First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: Show commits in topo order and name all commits. First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. * Applying: More documentation updates. First trying simple merge strategy to cherry-pick. -Finished one cherry-pick. ------------------------------------------------ The temporary tag 'pu-anchor' is me just being careful, in case 'git diff --git a/Documentation/install-webdoc.sh b/Documentation/install-webdoc.sh index 34d02a2418..37e67d1a14 100755 --- a/Documentation/install-webdoc.sh +++ b/Documentation/install-webdoc.sh @@ -12,7 +12,7 @@ do then : did not match elif test -f "$T/$h" && - $DIFF -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h" + $DIFF -u -I'^Last updated ' "$T/$h" "$h" then :; # up to date else diff --git a/Documentation/merge-config.txt b/Documentation/merge-config.txt index a403155052..b72f533970 100644 --- a/Documentation/merge-config.txt +++ b/Documentation/merge-config.txt @@ -15,6 +15,16 @@ merge.renameLimit:: during a merge; if not specified, defaults to the value of diff.renameLimit. +merge.renormalize:: + Tell git that canonical representation of files in the + repository has changed over time (e.g. earlier commits record + text files with CRLF line endings, but recent ones use LF line + endings). In such a repository, git can convert the data + recorded in commits to a canonical form before performing a + merge to reduce unnecessary conflicts. For more information, + see section "Merging branches with differing checkin/checkout + attributes" in linkgit:gitattributes[5]. + merge.stat:: Whether to print the diffstat between ORIG_HEAD and the merge result at the end of the merge. True by default. diff --git a/Documentation/merge-strategies.txt b/Documentation/merge-strategies.txt index a5bc1dbb95..049313d601 100644 --- a/Documentation/merge-strategies.txt +++ b/Documentation/merge-strategies.txt @@ -40,6 +40,18 @@ the other tree did, declaring 'our' history contains all that happened in it. theirs;; This is opposite of 'ours'. +renormalize;; + This runs a virtual check-out and check-in of all three stages + of a file when resolving a three-way merge. This option is + meant to be used when merging branches with different clean + filters or end-of-line normalization rules. See "Merging + branches with differing checkin/checkout attributes" in + linkgit:gitattributes[5] for details. + +no-renormalize;; + Disables the `renormalize` option. This overrides the + `merge.renormalize` configuration variable. + subtree[=path];; This option is a more advanced form of 'subtree' strategy, where the strategy makes a guess on how two trees must be shifted to diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index cc562a057a..e2237ae4a0 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -321,7 +321,7 @@ excluded from the output. reflog entries from the most recent one to older ones. When this option is used you cannot specify commits to exclude (that is, '{caret}commit', 'commit1..commit2', - nor 'commit1...commit2' notations cannot be used). + nor 'commit1\...commit2' notations cannot be used). + With '\--pretty' format other than oneline (for obvious reasons), this causes the output to have two extra lines of information diff --git a/Documentation/technical/api-merge.txt b/Documentation/technical/api-merge.txt new file mode 100644 index 0000000000..a7e050bb7a --- /dev/null +++ b/Documentation/technical/api-merge.txt @@ -0,0 +1,73 @@ +merge API +========= + +The merge API helps a program to reconcile two competing sets of +improvements to some files (e.g., unregistered changes from the work +tree versus changes involved in switching to a new branch), reporting +conflicts if found. The library called through this API is +responsible for a few things. + + * determining which trees to merge (recursive ancestor consolidation); + + * lining up corresponding files in the trees to be merged (rename + detection, subtree shifting), reporting edge cases like add/add + and rename/rename conflicts to the user; + + * performing a three-way merge of corresponding files, taking + path-specific merge drivers (specified in `.gitattributes`) + into account. + +Low-level (single file) merge +----------------------------- + +`ll_merge`:: + + Perform a three-way single-file merge in core. This is + a thin wrapper around `xdl_merge` that takes the path and + any merge backend specified in `.gitattributes` or + `.git/info/attributes` into account. Returns 0 for a + clean merge. + +The caller: + +1. allocates an mmbuffer_t variable for the result; +2. allocates and fills variables with the file's original content + and two modified versions (using `read_mmfile`, for example); +3. calls ll_merge(); +4. reads the output from result_buf.ptr and result_buf.size; +5. releases buffers when finished (free(ancestor.ptr); free(ours.ptr); + free(theirs.ptr); free(result_buf.ptr);). + +If the modifications do not merge cleanly, `ll_merge` will return a +nonzero value and `result_buf` will generally include a description of +the conflict bracketed by markers such as the traditional `<<<<<<<` +and `>>>>>>>`. + +The `ancestor_label`, `our_label`, and `their_label` parameters are +used to label the different sides of a conflict if the merge driver +supports this. + +The `flag` parameter is a bitfield: + + - The `LL_OPT_VIRTUAL_ANCESTOR` bit indicates whether this is an + internal merge to consolidate ancestors for a recursive merge. + + - The `LL_OPT_FAVOR_MASK` bits allow local conflicts to be automatically + resolved in favor of one side or the other (as in 'git merge-file' + `--ours`/`--theirs`/`--union`). + They can be populated by `create_ll_flag`, whose argument can be + `XDL_MERGE_FAVOR_OURS`, `XDL_MERGE_FAVOR_THEIRS`, or + `XDL_MERGE_FAVOR_UNION`. + +Everything else +--------------- + +Talk about <merge-recursive.h> and merge_file(): + + - merge_trees() to merge with rename detection + - merge_recursive() for ancestor consolidation + - try_merge_command() for other strategies + - conflict format + - merge options + +(Daniel, Miklos, Stephan, JC) diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 312e3b2e2b..c5d141cd63 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -201,7 +201,7 @@ The last element of the array must be `OPT_END()`. If not stated otherwise, interpret the arguments as follows: * `short` is a character for the short option - (e.g. `\'e\'` for `-e`, use `0` to omit), + (e.g. `{apostrophe}e{apostrophe}` for `-e`, use `0` to omit), * `long` is a string for the long option (e.g. `"example"` for `\--example`, use `NULL` to omit), @@ -228,10 +228,10 @@ The function must be defined in this form: The callback mechanism is as follows: * Inside `func`, the only interesting member of the structure - given by `opt` is the void pointer `opt->value`. - `\*opt->value` will be the value that is saved into `var`, if you + given by `opt` is the void pointer `opt\->value`. + `\*opt\->value` will be the value that is saved into `var`, if you use `OPT_CALLBACK()`. - For example, do `*(unsigned long *)opt->value = 42;` to get 42 + For example, do `*(unsigned long *)opt\->value = 42;` to get 42 into an `unsigned long` variable. * Return value `0` indicates success and non-zero return diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 22aee34d4a..fecc4eb5b3 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -4251,9 +4251,9 @@ Two things are interesting here: negative numbers in case of different errors--and 0 on success. - the variable `sha1` in the function signature of `get_sha1()` is `unsigned - char \*`, but is actually expected to be a pointer to `unsigned + char {asterisk}`, but is actually expected to be a pointer to `unsigned char[20]`. This variable will contain the 160-bit SHA-1 of the given - commit. Note that whenever a SHA-1 is passed as `unsigned char \*`, it + commit. Note that whenever a SHA-1 is passed as `unsigned char {asterisk}`, it is the binary representation, as opposed to the ASCII representation in hex characters, which is passed as `char *`. |