diff options
Diffstat (limited to 'Documentation')
39 files changed, 844 insertions, 104 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index f424dbd..4d90c77 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -18,6 +18,14 @@ code. For Git in general, three rough rules are: judgement call, the decision based more on real world constraints people face than what the paper standard says. + - Fixing style violations while working on a real change as a + preparatory clean-up step is good, but otherwise avoid useless code + churn for the sake of conforming to the style. + + "Once it _is_ in the tree, it's not really worth the patch noise to + go and fix it up." + Cf. http://article.gmane.org/gmane.linux.kernel/943020 + Make your code readable and sensible, and don't try to be clever. As for more concrete guidelines, just imitate the existing code @@ -34,7 +42,17 @@ For shell scripts specifically (not exhaustive): - We use tabs for indentation. - - Case arms are indented at the same depth as case and esac lines. + - Case arms are indented at the same depth as case and esac lines, + like this: + + case "$variable" in + pattern1) + do this + ;; + pattern2) + do that + ;; + esac - Redirection operators should be written with space before, but no space after them. In other words, write 'echo test >"$file"' @@ -43,6 +61,14 @@ For shell scripts specifically (not exhaustive): redirection target in a variable (as shown above), our code does so because some versions of bash issue a warning without the quotes. + (incorrect) + cat hello > world < universe + echo hello >$world + + (correct) + cat hello >world <universe + echo hello >"$world" + - We prefer $( ... ) for command substitution; unlike ``, it properly nests. It should have been the way Bourne spelled it from day one, but unfortunately isn't. @@ -81,14 +107,33 @@ For shell scripts specifically (not exhaustive): "then" should be on the next line for if statements, and "do" should be on the next line for "while" and "for". + (incorrect) + if test -f hello; then + do this + fi + + (correct) + if test -f hello + then + do this + fi + - We prefer "test" over "[ ... ]". - We do not write the noiseword "function" in front of shell functions. - - We prefer a space between the function name and the parentheses. The - opening "{" should also be on the same line. - E.g.: my_function () { + - We prefer a space between the function name and the parentheses, + and no space inside the parentheses. The opening "{" should also + be on the same line. + + (incorrect) + my_function(){ + ... + + (correct) + my_function () { + ... - As to use of grep, stick to a subset of BRE (namely, no \{m,n\}, [::], [==], or [..]) for portability. @@ -106,6 +151,19 @@ For shell scripts specifically (not exhaustive): interface translatable. See "Marking strings for translation" in po/README. + - We do not write our "test" command with "-a" and "-o" and use "&&" + or "||" to concatenate multiple "test" commands instead, because + the use of "-a/-o" is often error-prone. E.g. + + test -n "$x" -a "$a" = "$b" + + is buggy and breaks when $x is "=", but + + test -n "$x" && test "$a" = "$b" + + does not have such a problem. + + For C programs: - We use tabs to indent, and interpret tabs as taking up to @@ -149,7 +207,7 @@ For C programs: of "else if" statements, it can make sense to add braces to single line blocks. - - We try to avoid assignments inside if(). + - We try to avoid assignments in the condition of an "if" statement. - Try to make your code understandable. You may put comments in, but comments invariably tend to stale out when the code @@ -177,6 +235,88 @@ For C programs: - Double negation is often harder to understand than no negation at all. + - There are two schools of thought when it comes to comparison, + especially inside a loop. Some people prefer to have the less stable + value on the left hand side and the more stable value on the right hand + side, e.g. if you have a loop that counts variable i down to the + lower bound, + + while (i > lower_bound) { + do something; + i--; + } + + Other people prefer to have the textual order of values match the + actual order of values in their comparison, so that they can + mentally draw a number line from left to right and place these + values in order, i.e. + + while (lower_bound < i) { + do something; + i--; + } + + Both are valid, and we use both. However, the more "stable" the + stable side becomes, the more we tend to prefer the former + (comparison with a constant, "i > 0", is an extreme example). + Just do not mix styles in the same part of the code and mimic + existing styles in the neighbourhood. + + - There are two schools of thought when it comes to splitting a long + logical line into multiple lines. Some people push the second and + subsequent lines far enough to the right with tabs and align them: + + if (the_beginning_of_a_very_long_expression_that_has_to || + span_more_than_a_single_line_of || + the_source_text) { + ... + + while other people prefer to align the second and the subsequent + lines with the column immediately inside the opening parenthesis, + with tabs and spaces, following our "tabstop is always a multiple + of 8" convention: + + if (the_beginning_of_a_very_long_expression_that_has_to || + span_more_than_a_single_line_of || + the_source_text) { + ... + + Both are valid, and we use both. Again, just do not mix styles in + the same part of the code and mimic existing styles in the + neighbourhood. + + - When splitting a long logical line, some people change line before + a binary operator, so that the result looks like a parse tree when + you turn your head 90-degrees counterclockwise: + + if (the_beginning_of_a_very_long_expression_that_has_to + || span_more_than_a_single_line_of_the_source_text) { + + while other people prefer to leave the operator at the end of the + line: + + if (the_beginning_of_a_very_long_expression_that_has_to || + span_more_than_a_single_line_of_the_source_text) { + + Both are valid, but we tend to use the latter more, unless the + expression gets fairly complex, in which case the former tends to + be easier to read. Again, just do not mix styles in the same part + of the code and mimic existing styles in the neighbourhood. + + - When splitting a long logical line, with everything else being + equal, it is preferable to split after the operator at higher + level in the parse tree. That is, this is more preferable: + + if (a_very_long_variable * that_is_used_in + + a_very_long_expression) { + ... + + than + + if (a_very_long_variable * + that_is_used_in + a_very_long_expression) { + ... + - Some clever tricks, like using the !! operator with arithmetic constructs, can be extremely confusing to others. Avoid them, unless there is a compelling reason to use them. diff --git a/Documentation/Makefile b/Documentation/Makefile index fc6b2cf..cea0e7a 100644 --- a/Documentation/Makefile +++ b/Documentation/Makefile @@ -59,6 +59,7 @@ SP_ARTICLES += howto/recover-corrupted-blob-object SP_ARTICLES += howto/recover-corrupted-object-harder SP_ARTICLES += howto/rebuild-from-update-hook SP_ARTICLES += howto/rebase-from-internal-branch +SP_ARTICLES += howto/keep-canonical-history-correct SP_ARTICLES += howto/maintain-git API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt))) SP_ARTICLES += $(API_DOCS) diff --git a/Documentation/RelNotes/2.1.0.txt b/Documentation/RelNotes/2.1.0.txt new file mode 100644 index 0000000..17360e5 --- /dev/null +++ b/Documentation/RelNotes/2.1.0.txt @@ -0,0 +1,280 @@ +Git v2.1 Release Notes +====================== + +Backward compatibility notes +---------------------------- + + * The default value we give to the environment variable LESS has been + changed from "FRSX" to "FRX", losing "S" (chop long lines instead + of wrapping). Existing users who prefer not to see line-wrapped + output may want to set + + $ git config core.pager "less -S" + + to restore the traditional behaviour. It is expected that people + find output from the most subcommands easier to read with the new + default, except for "blame" which tends to produce really long + lines. To override the new default only for "git blame", you can + do this: + + $ git config pager.blame "less -S" + + * A few disused directories in contrib/ have been retired. + + +Updates since v2.0 +------------------ + +UI, Workflows & Features + + * Since the very beginning of Git, we gave the LESS environment a + default value "FRSX" when we spawn "less" as the pager. "S" (chop + long lines instead of wrapping) has been removed from this default + set of options, because it is more or less a personal taste thing, + as opposed to others that have good justifications (i.e. "R" is + very much justified because many kinds of output we produce are + colored and "FX" is justified because output we produce is often + shorter than a page). + + * The logic and data used to compute the display width needed for + UTF-8 strings have been updated to match Unicode 6.3 better. + + * HTTP-based transports learned to propagate the error messages from + the webserver better to the client coming over the HTTP transport. + + * The "core.preloadindex" configuration variable is by default + enabled, allowing modern platforms to take advantage of the + multiple cores they have. + + * "git commit --date=<date>" option learned to read from more + timestamp formats, including "--date=now". + + * The `core.commentChar` configuration variable is used to specify a + custom comment character other than the default "#" to be used in + the commit log editor. This can be set to `auto` to attempt to + choose a different character that does not conflict with what + already starts a line in the message being edited for cases like + "git commit --amend". + + * "git format-patch" learned --signature-file=<file> to take the mail + signature from. + + * "git grep" learned grep.fullname configuration variable to force + "--full-name" to be default. This may cause regressions on + scripted users that do not expect this new behaviour. + + * "git imap-send" learned to ask the credential helper for auth + material. + + * "git log" and friends now understand the value "auto" set to the + "log.decorate" configuration variable to enable the "--decorate" + option automatically when the output is sent to tty. + + * "git merge" without argument, even when there is an upstream + defined for the current branch, refused to run until + merge.defaultToUpstream is set to true. Flip the default of that + configuration variable to true. + + * "git mergetool" learned to drive the vimdiff3 backend. + + * mergetool.prompt used to default to 'true', always asking "do you + really want to run the tool on this path?". Among the two + purposes this prompt serves, ignore the use case to confirm that + the user wants to view particular path with the named tool, and + redefine the meaning of the prompt only to confirm the choice of + the tool made by the autodetection (for those who configured the + tool explicitly, the prompt shown for the latter purpose is + simply annoying). + + Strictly speaking, this is a backward incompatible change and the + users need to explicitly set the variable to 'true' if they want + to resurrect the now-ignored use case. + + * "git replace" learned the "--edit" subcommand. + + * "git svn" learned to cope with malformed timestamps with only one + digit in the hour part, e.g. 2014-01-07T5:01:02.048176Z, emitted + by some broken subversion server implementations. + + * "git tag" when editing the tag message shows the name of the tag + being edited as a comment in the editor. + + +Performance, Internal Implementation, etc. + + * Build procedure for 'subtree' (in contrib/) has been cleaned up. + + * The `core.deltabasecachelimit` used to default to 16 MiB , but this + proved to be too small, and has been bumped to 96 MiB. + + * "git blame" has been optimized greatly by reorganising the data + structure that is used to keep track of the work to be done. + + * "git diff" that compares 3-or-more trees (e.g. parents and the + result of a merge) have been optimized. + + * The API to update/delete references are being converted to handle + updates to multiple references in a transactional way. As an + example, "update-ref --stdin [-z]" has been updated to use this + API. + + * Parts of the test scripts can be skipped by using a range notation, + e.g. "sh t1234-test.sh --run='1-4 6 8-'" to omit test piece 5 and 7 + and run everything else. + + +Also contains various documentation updates and code clean-ups. + + +Fixes since v2.0 +---------------- + +Unless otherwise noted, all the fixes since v2.0 in the maintenance +track are contained in this release (see the maintenance releases' +notes for details). + + * We used to unconditionally disable the pager in the pager process + we spawn to feed out output, but that prevented people who want to + run "less" within "less" from doing so. + (merge c0459ca je/pager-do-not-recurse later to maint). + + * Tools that read diagnostic output in our standard error stream do + not want to see terminal control sequence (e.g. erase-to-eol). + Detect them by checking if the standard error stream is connected + to a tty. + (merge 38de156 mn/sideband-no-ansi later to maint). + + * Mishandling of patterns in .gitignore that has trailing SPs quoted + with backslashes (e.g. ones that end with "\ ") have been + corrected. + (merge e61a6c1 pb/trim-trailing-spaces later to maint). + + * Reworded the error message given upon a failure to open an existing + loose object file due to e.g. permission issues; it was reported as + the object being corrupt, but that is not quite true. + (merge d6c8a05 jk/report-fail-to-read-objects-better later to maint). + + * The "%<(10,trunc)%s" pretty format specifier in the log family of + commands is used to truncate the string to a given length (e.g. 10 + in the example) with padding to column-align the output, but did + not take into account that number of bytes and number of display + columns are different. + (merge 7d50987 as/pretty-truncate later to maint). + + * The "mailmap.file" configuration option did not support the tilde + expansion (i.e. ~user/path and ~/path). + (merge 9352fd5 ow/config-mailmap-pathname later to maint). + + * The completion scripts (in contrib/) did not know about quite a few + options that are common between "git merge" and "git pull", and a + couple of options unique to "git merge". + (merge 8fee872 jk/complete-merge-pull later to maint). + + * "--ignore-space-change" option of "git apply" ignored the spaces + at the beginning of line too aggressively, which is inconsistent + with the option of the same name "diff" and "git diff" have. + (merge 14d3bb4 jc/apply-ignore-whitespace later to maint). + + * "git blame" miscounted number of columns needed to show localized + timestamps, resulting in jaggy left-side-edge of the source code + lines in its output. + (merge dd75553 jx/blame-align-relative-time later to maint). + + * "git blame" assigned the blame to the copy in the working-tree if + the repository is set to core.autocrlf=input and the file used CRLF + line endings. + (merge 4d4813a bc/blame-crlf-test later to maint). + + * "git commit --allow-empty-messag -C $commit" did not work when the + commit did not have any log message. + (merge 076cbd6 jk/commit-C-pick-empty later to maint). + + * "git diff --find-copies-harder" sometimes pretended as if the mode + bits have changed for paths that are marked with assume-unchanged + bit. + (merge 5304810 jk/diff-files-assume-unchanged later to maint). + + * "git format-patch" did not enforce the rule that the "--follow" + option from the log/diff family of commands must be used with + exactly one pathspec. + (merge dd63f16 jk/diff-follow-must-take-one-pathspec later to maint). + + * "git gc --auto" was recently changed to run in the background to + give control back early to the end-user sitting in front of the + terminal, but it forgot that housekeeping involving reflogs should + be done without other processes competing for accesses to the refs. + (merge 62aad18 nd/daemonize-gc later to maint). + + * "git grep -O" to show the lines that hit in the pager did not work + well with case insensitive search. We now spawn "less" with its + "-I" option when it is used as the pager (which is the default). + (merge f7febbe sk/spawn-less-case-insensitively-from-grep-O-i later to maint). + + * We used to disable threaded "git index-pack" on platforms without + thread-safe pread(); use a different workaround for such + platforms to allow threaded "git index-pack". + (merge 3953949 nd/index-pack-one-fd-per-thread later to maint). + + * The error reporting from "git index-pack" has been improved to + distinguish missing objects from type errors. + (merge 77583e7 jk/index-pack-report-missing later to maint). + + * "git mailinfo" used to read beyond the end of header string while + parsing an incoming e-mail message to extract the patch. + (merge b1a013d rs/mailinfo-header-cmp later to maint). + + * On a case insensitive filesystem, merge-recursive incorrectly + deleted the file that is to be renamed to a name that is the same + except for case differences. + (merge baa37bf dt/merge-recursive-case-insensitive later to maint). + + * "git pack-objects" unnecessarily copied the previous contents when + extending the hashtable, even though it will populate the table + from scratch anyway. + (merge fb79947 rs/pack-objects-no-unnecessary-realloc later to maint). + + * "git rerere forget" did not work well when merge.conflictstyle + was set to a non-default value. + (merge de3d8bb fc/rerere-conflict-style later to maint). + + * "git remote rm" and "git remote prune" can involve removing many + refs at once, which is not a very efficient thing to do when very + many refs exist in the packed-refs file. + (merge e6bea66 jl/remote-rm-prune later to maint). + + * "git log --exclude=<glob> --all | git shortlog" worked as expected, + but "git shortlog --exclude=<glob> --all", which is supposed to be + identical to the above pipeline, was not accepted at the command + line argument parser level. + (merge eb07774 jc/shortlog-ref-exclude later to maint). + + * The autostash mode of "git rebase -i" did not restore the dirty + working tree state if the user aborted the interactive rebase by + emptying the insn sheet. + (merge ddb5432 rr/rebase-autostash-fix later to maint). + + * "git show -s" (i.e. show log message only) used to incorrectly emit + an extra blank line after a merge commit. + (merge ad2f725 mk/show-s-no-extra-blank-line-for-merges later to maint). + + * "git status", even though it is a read-only operation, tries to + update the index with refreshed lstat(2) info to optimize future + accesses to the working tree opportunistically, but this could + race with a "read-write" operation that modify the index while it + is running. Detect such a race and avoid overwriting the index. + (merge 426ddee ym/fix-opportunistic-index-update-race later to maint). + + * "git status" (and "git commit") behaved as if changes in a modified + submodule are not there if submodule.*.ignore configuration is set, + which was misleading. The configuration is only to unclutter diff + output during the course of development, and should not to hide + changes in the "status" output to cause the users forget to commit + them. + (merge c215d3d jl/status-added-submodule-is-never-ignored later to maint). + + * "git update-index --cacheinfo" in 2.0 release crashed on a + malformed command line. + (merge c8e1ee4 jc/rev-parse-argh-dashed-multi-words later to maint). + + * The mode to run tests with HTTP server tests disabled was broken. + (merge afa53fe na/no-http-test-in-the-middle later to maint). diff --git a/Documentation/config.txt b/Documentation/config.txt index 1932e9b..9f467d3 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -381,7 +381,7 @@ false), while all other repositories are assumed to be bare (bare core.worktree:: Set the path to the root of the working tree. This can be overridden by the GIT_WORK_TREE environment - variable and the '--work-tree' command line option. + variable and the '--work-tree' command-line option. The value can be an absolute path or relative to the path to the .git directory, which is either specified by --git-dir or GIT_DIR, or automatically discovered. @@ -489,7 +489,7 @@ core.deltaBaseCacheLimit:: to avoid unpacking and decompressing frequently used base objects multiple times. + -Default is 16 MiB on all platforms. This should be reasonable +Default is 96 MiB on all platforms. This should be reasonable for all users/operating systems, except on the largest projects. You probably do not need to adjust this value. + @@ -523,7 +523,7 @@ core.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. + command-line argument and write the password on its STDOUT. core.attributesfile:: In addition to '.gitattributes' (per-directory) and @@ -544,6 +544,9 @@ core.commentchar:: messages consider a line that begins with this character commented, and removes them after the editor returns (default '#'). ++ +If set to "auto", `git-commit` would select a character that is not +the beginning character of any line in existing commit messages. sequence.editor:: Text editor used by `git rebase -i` for editing the rebase instruction file. @@ -558,14 +561,19 @@ core.pager:: configuration, then `$PAGER`, and then the default chosen at compile time (usually 'less'). + -When the `LESS` environment variable is unset, Git sets it to `FRSX` +When the `LESS` environment variable is unset, Git sets it to `FRX` (if `LESS` environment variable is set, Git does not change it at all). If you want to selectively override Git's default setting -for `LESS`, you can set `core.pager` to e.g. `less -+S`. This will +for `LESS`, you can set `core.pager` to e.g. `less -S`. This will be passed to the shell by Git, which will translate the final -command to `LESS=FRSX less -+S`. The environment tells the command -to set the `S` option to chop long lines but the command line -resets it to the default to fold long lines. +command to `LESS=FRX less -S`. The environment does not set the +`S` option but the command line does, instructing less to truncate +long lines. Similarly, setting `core.pager` to `less -+F` will +deactivate the `F` option specified by the environment from the +command-line, deactivating the "quit if one screen" behavior of +`less`. One can specifically activate some flags for particular +commands: for example, setting `pager.blame` to `less -S` enables +line truncation only for `git blame`. + Likewise, when the `LV` environment variable is unset, Git sets it to `-c`. You can override this setting by exporting `LV` with @@ -613,9 +621,9 @@ core.preloadindex:: + This can speed up operations like 'git diff' and 'git status' especially on filesystems like NFS that have weak caching semantics and thus -relatively high IO latencies. With this set to 'true', Git will do the +relatively high IO latencies. When enabled, Git will do the index comparison to the filesystem data in parallel, allowing -overlapping IO's. +overlapping IO's. Defaults to true. core.createObject:: You can set this to 'link', in which case a hardlink followed by @@ -1114,6 +1122,10 @@ format.signature:: Set this variable to the empty string ("") to suppress signature generation. +format.signaturefile:: + Works just like format.signature except the contents of the + file specified by this variable will be used as the signature. + format.suffix:: The default for format-patch is to output files with the suffix `.patch`. Use this variable to change that suffix (make sure to @@ -1324,7 +1336,7 @@ grep.extendedRegexp:: gpg.program:: Use this custom program instead of "gpg" found on $PATH when making or verifying a PGP signature. The program must support the - same command line interface as GPG, namely, to verify a detached + same command-line interface as GPG, namely, to verify a detached signature, "gpg --verify $file - <$signature" is run, and the program is expected to signal a good signature by exiting with code 0, and to generate an ascii-armored detached signature, the @@ -2293,9 +2305,11 @@ status.submodulesummary:: --summary-limit option of linkgit:git-submodule[1]). Please note that the summary output command will be suppressed for all submodules when `diff.ignoreSubmodules` is set to 'all' or only - for those submodules where `submodule.<name>.ignore=all`. To + for those submodules where `submodule.<name>.ignore=all`. The only + exception to that rule is that status and commit will show staged + submodule changes. To also view the summary for ignored submodules you can either use - the --ignore-submodules=dirty command line option or the 'git + the --ignore-submodules=dirty command-line option or the 'git submodule summary' command, which shows a similar output but does not honor these settings. @@ -2317,14 +2331,16 @@ submodule.<name>.branch:: submodule.<name>.fetchRecurseSubmodules:: This option can be used to control recursive fetching of this submodule. It can be overridden by using the --[no-]recurse-submodules - command line option to "git fetch" and "git pull". + command-line option to "git fetch" and "git pull". This setting will override that from in the linkgit:gitmodules[5] file. submodule.<name>.ignore:: Defines under what circumstances "git status" and the diff family show a submodule as modified. When set to "all", it will never be considered - modified, "dirty" will ignore all changes to the submodules work tree and + modified (but it will nonetheless show up in the output of status and + commit when it has been staged), "dirty" will ignore all changes + to the submodules work tree and takes only differences between the HEAD of the submodule and the commit recorded in the superproject into account. "untracked" will additionally let submodules with modified tracked files in their work tree show up. diff --git a/Documentation/diff-config.txt b/Documentation/diff-config.txt index f07b451..b001779 100644 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@ -76,7 +76,7 @@ diff.ignoreSubmodules:: this setting when reporting uncommitted changes. Setting it to 'all' disables the submodule summary normally shown by 'git commit' and 'git status' when 'status.submodulesummary' is set unless it is - overridden by using the --ignore-submodules command line option. + overridden by using the --ignore-submodules command-line option. The 'git submodule' commands are not affected by this setting. diff.mnemonicprefix:: diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index f986c5c..4cb52a7 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -117,7 +117,7 @@ $ git bisect visualize `view` may also be used as a synonym for `visualize`. If the 'DISPLAY' environment variable is not set, 'git log' is used -instead. You can also give command line options such as `-p` and +instead. You can also give command-line options such as `-p` and `--stat`. ------------ diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index e9917b8..9dfa1a5 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -256,7 +256,7 @@ All writing options will per default write to the repository specific configuration file. Note that this also affects options like '--replace-all' and '--unset'. *'git config' will only ever change one file at a time*. -You can override these rules either by command line options or by environment +You can override these rules either by command-line options or by environment variables. The '--global' and the '--system' options will limit the file used to the global or system-wide file respectively. The GIT_CONFIG environment variable has a similar effect, but you can specify any filename you want. diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 223f731..a69b361 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -169,7 +169,7 @@ Git configuration files in that directory are readable by `<user>`. --forbid-override=<service>:: Allow/forbid overriding the site-wide default with per repository configuration. By default, all the services - are overridable. + may be overridden. --[no-]informative-errors:: When informative errors are turned on, git-daemon will report @@ -184,7 +184,7 @@ Git configuration files in that directory are readable by `<user>`. Every time a client connects, first run an external command specified by the <path> with service name (e.g. "upload-pack"), path to the repository, hostname (%H), canonical hostname - (%CH), ip address (%IP), and tcp port (%P) as its command line + (%CH), IP address (%IP), and TCP port (%P) as its command-line arguments. The external command can decide to decline the service by exiting with a non-zero status (or to allow it by exiting with a zero status). It can also look at the $REMOTE_ADDR @@ -204,7 +204,7 @@ SERVICES -------- These services can be globally enabled/disabled using the -command line options of this command. If a finer-grained +command-line options of this command. If finer-grained control is desired (e.g. to allow 'git archive' to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 85f1f30..221506b 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -105,6 +105,10 @@ marks the same across runs. in the commit (as opposed to just listing the files which are different from the commit's first parent). +--refspec:: + Apply the specified refspec to each ref exported. Multiple of them can + be specified. + [<git-rev-list-args>...]:: A list of arguments, acceptable to 'git rev-parse' and 'git rev-list', that specifies the specific objects and references diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index fd22a9a..377eeaa 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -231,7 +231,7 @@ Date Formats ~~~~~~~~~~~~ The following date formats are supported. A frontend should select the format it will use for this import by passing the format name -in the \--date-format=<fmt> command line option. +in the \--date-format=<fmt> command-line option. `raw`:: This is the Git native format and is `<time> SP <offutc>`. @@ -348,7 +348,7 @@ and control the current import process. More detailed discussion `done`:: Marks the end of the stream. This command is optional unless the `done` feature was requested using the - `--done` command line option or `feature done` command. + `--done` command-line option or `feature done` command. `cat-blob`:: Causes fast-import to print a blob in 'cat-file --batch' @@ -437,7 +437,7 @@ the email address from the other fields in the line. Note that of bytes, except `LT`, `GT` and `LF`. `<name>` is typically UTF-8 encoded. The time of the change is specified by `<when>` using the date format -that was selected by the \--date-format=<fmt> command line option. +that was selected by the \--date-format=<fmt> command-line option. See ``Date Formats'' above for the set of supported formats, and their syntax. @@ -483,6 +483,9 @@ Marks must be declared (via `mark`) before they can be used. * Any valid Git SHA-1 expression that resolves to a commit. See ``SPECIFYING REVISIONS'' in linkgit:gitrevisions[7] for details. +* The special null SHA-1 (40 zeros) specifies that the branch is to be + removed. + The special case of restarting an incremental import from the current branch value should be written as: ---- @@ -1085,7 +1088,7 @@ Option commands must be the first commands on the input (not counting feature commands), to give an option command after any non-option command is an error. -The following commandline options change import semantics and may therefore +The following command-line options change import semantics and may therefore not be passed as option: * date-format @@ -1099,7 +1102,7 @@ not be passed as option: If the `done` feature is not in use, treated as if EOF was read. This can be used to tell fast-import to finish early. -If the `--done` command line option or `feature done` command is +If the `--done` command-line option or `feature done` command is in use, the `done` command is mandatory and marks the end of the stream. diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index 5c0a4ab..c0fd470 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -14,6 +14,7 @@ SYNOPSIS [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] [--signature=<signature> | --no-signature] + [--signature-file=<file>] [-n | --numbered | -N | --no-numbered] [--start-number <n>] [--numbered-files] [--in-reply-to=Message-Id] [--suffix=.<sfx>] @@ -233,6 +234,9 @@ configuration options in linkgit:git-notes[1] to use this workflow). signature option is omitted the signature defaults to the Git version number. +--signature-file=<file>:: + Works just like --signature except the signature is read from a file. + --suffix=.<sfx>:: Instead of using `.patch` as the suffix for generated filenames, use specified suffix. A common alternative is diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index f837334..31811f1 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -53,6 +53,9 @@ grep.extendedRegexp:: option is ignored when the 'grep.patternType' option is set to a value other than 'default'. +grep.fullName:: + If set to true, enable '--full-name' option by default. + OPTIONS ------- diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index b21e9d7..3956525 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -80,9 +80,9 @@ CONFIGURATION VARIABLES help.format ~~~~~~~~~~~ -If no command line option is passed, the 'help.format' configuration +If no command-line option is passed, the 'help.format' configuration variable will be checked. The following values are supported for this -variable; they make 'git help' behave as their corresponding command +variable; they make 'git help' behave as their corresponding command- line option: * "man" corresponds to '-m|--man', @@ -93,15 +93,15 @@ 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 +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{litdd}browse[1]. man.viewer ~~~~~~~~~~ -The 'man.viewer' config variable will be checked if the 'man' format -is chosen. The following values are currently supported: +The 'man.viewer' configuration variable will be checked if the 'man' +format is chosen. The following values are currently supported: * "man": use the 'man' program as usual, * "woman": use 'emacsclient' to launch the "woman" mode in emacs @@ -124,7 +124,7 @@ For example, this configuration: viewer = woman ------------------------------------------------ -will try to use konqueror first. But this may fail (for example if +will try to use konqueror first. But this may fail (for example, if DISPLAY is not set) and in that case emacs' woman mode will be tried. If everything fails, or if no viewer is configured, the viewer specified diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index c0856a6..e26f01f 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -185,15 +185,15 @@ specifies the format of exclude patterns. These exclude patterns come from these places, in order: - 1. The command line flag --exclude=<pattern> specifies a + 1. The command-line flag --exclude=<pattern> specifies a single pattern. Patterns are ordered in the same order they appear in the command line. - 2. The command line flag --exclude-from=<file> specifies a + 2. The command-line flag --exclude-from=<file> specifies a file containing a list of patterns. Patterns are ordered in the same order they appear in the file. - 3. The command line flag --exclude-per-directory=<name> specifies + 3. The command-line flag --exclude-per-directory=<name> specifies a name of the file in each directory 'git ls-files' examines, normally `.gitignore`. Files in deeper directories take precedence. Patterns are ordered in the diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt index a3c1fa3..cf2c374 100644 --- a/Documentation/git-merge.txt +++ b/Documentation/git-merge.txt @@ -101,9 +101,8 @@ commit or stash your changes before running 'git merge'. Specifying more than one commit will create a merge with more than two parents (affectionately called an Octopus merge). + -If no commit is given from the command line, and if `merge.defaultToUpstream` -configuration variable is set, merge the remote-tracking branches -that the current branch is configured to use as its upstream. +If no commit is given from the command line, merge the remote-tracking +branches that the current branch is configured to use as its upstream. See also the configuration section of this manual page. diff --git a/Documentation/git-mergetool.txt b/Documentation/git-mergetool.txt index 07137f2..e846c2e 100644 --- a/Documentation/git-mergetool.txt +++ b/Documentation/git-mergetool.txt @@ -71,11 +71,13 @@ success of the resolution after the custom tool has exited. --no-prompt:: Don't prompt before each invocation of the merge resolution program. + This is the default if the merge resolution program is + explicitly specified with the `--tool` option or with the + `merge.tool` configuration variable. --prompt:: - Prompt before each invocation of the merge resolution program. - This is the default behaviour; the option is provided to - override any configuration settings. + Prompt before each invocation of the merge resolution program + to give the user a chance to skip the path. TEMPORARY FILES --------------- diff --git a/Documentation/git-patch-id.txt b/Documentation/git-patch-id.txt index 312c3b1..31efc58 100644 --- a/Documentation/git-patch-id.txt +++ b/Documentation/git-patch-id.txt @@ -8,14 +8,14 @@ git-patch-id - Compute unique ID for a patch SYNOPSIS -------- [verse] -'git patch-id' < <patch> +'git patch-id' [--stable | --unstable] < <patch> DESCRIPTION ----------- -A "patch ID" is nothing but a SHA-1 of the diff associated with a patch, with -whitespace and line numbers ignored. As such, it's "reasonably stable", but at -the same time also reasonably unique, i.e., two patches that have the same "patch -ID" are almost guaranteed to be the same thing. +A "patch ID" is nothing but a sum of SHA-1 of the file diffs associated with a +patch, with whitespace and line numbers ignored. As such, it's "reasonably +stable", but at the same time also reasonably unique, i.e., two patches that +have the same "patch ID" are almost guaranteed to be the same thing. IOW, you can use this thing to look for likely duplicate commits. @@ -27,6 +27,33 @@ This can be used to make a mapping from patch ID to commit ID. OPTIONS ------- + +--stable:: + Use a "stable" sum of hashes as the patch ID. With this option: + - Reordering file diffs that make up a patch does not affect the ID. + In particular, two patches produced by comparing the same two trees + with two different settings for "-O<orderfile>" result in the same + patch ID signature, thereby allowing the computed result to be used + as a key to index some meta-information about the change between + the two trees; + + - Result is different from the value produced by git 1.9 and older + or produced when an "unstable" hash (see --unstable below) is + configured - even when used on a diff output taken without any use + of "-O<orderfile>", thereby making existing databases storing such + "unstable" or historical patch-ids unusable. + + This is the default if patchid.stable is set to true. + +--unstable:: + Use an "unstable" hash as the patch ID. With this option, + the result produced is compatible with the patch-id value produced + by git 1.9 and older. Users with pre-existing databases storing + patch-ids produced by git 1.9 and older (who do not deal with reordered + patches) may want to use this option. + + This is the default. + <patch>:: The diff to create the ID of. diff --git a/Documentation/git-read-tree.txt b/Documentation/git-read-tree.txt index 056c0db..fa1d557 100644 --- a/Documentation/git-read-tree.txt +++ b/Documentation/git-read-tree.txt @@ -283,7 +283,7 @@ merge. The different stages represent the "result tree" (stage 0, aka you are trying to merge (stage 2 and 3 respectively). The order of stages 1, 2 and 3 (hence the order of three -<tree-ish> command line arguments) are significant when you +<tree-ish> command-line arguments) are significant when you start a 3-way merge with an index file that is already populated. Here is an outline of how the algorithm works: diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt index 0a02f70..61461b9 100644 --- a/Documentation/git-replace.txt +++ b/Documentation/git-replace.txt @@ -9,6 +9,7 @@ SYNOPSIS -------- [verse] 'git replace' [-f] <object> <replacement> +'git replace' [-f] --edit <object> 'git replace' -d <object>... 'git replace' [--format=<format>] [-l [<pattern>]] @@ -63,6 +64,15 @@ OPTIONS --delete:: Delete existing replace refs for the given objects. +--edit <object>:: + Edit an object's content interactively. The existing content + for <object> is pretty-printed into a temporary file, an + editor is launched on the file, and the result is parsed to + create a new object of the same type as <object>. A + replacement ref is then created to replace <object> with the + newly created object. See linkgit:git-var[1] for details about + how the editor will be chosen. + -l <pattern>:: --list <pattern>:: List replace refs for objects that match the given pattern (or @@ -92,7 +102,9 @@ CREATING REPLACEMENT OBJECTS linkgit:git-filter-branch[1], linkgit:git-hash-object[1] and linkgit:git-rebase[1], among other git commands, can be used to create -replacement objects from existing objects. +replacement objects from existing objects. The `--edit` option can +also be used with 'git replace' to create a replacement object by +editing an existing object. If you want to replace many blobs, trees or commits that are part of a string of commits, you may just want to create a replacement string of @@ -117,6 +129,8 @@ linkgit:git-filter-branch[1] linkgit:git-rebase[1] linkgit:git-tag[1] linkgit:git-branch[1] +linkgit:git-commit[1] +linkgit:git-var[1] linkgit:git[1] GIT diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index f0e57a5..d0fa18a 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -20,7 +20,7 @@ files in the directory), or directly as a revision list. In the last case, any format accepted by linkgit:git-format-patch[1] can be passed to git send-email. -The header of the email is configurable by command line options. If not +The header of the email is configurable via command-line options. If not specified on the command line, the user will be prompted with a ReadLine enabled interface to provide the necessary information. @@ -68,7 +68,7 @@ The --cc option must be repeated for each user you want on the cc list. When '--compose' is used, git send-email will use the From, Subject, and In-Reply-To headers specified in the message. If the body of the message (what you type after the headers and a blank line) only contains blank -(or Git: prefixed) lines the summary won't be sent, but From, Subject, +(or Git: prefixed) lines, the summary won't be sent, but From, Subject, and In-Reply-To headers will be used unless they are removed. + Missing From or In-Reply-To headers will be prompted for. @@ -78,7 +78,7 @@ See the CONFIGURATION section for 'sendemail.multiedit'. --from=<address>:: Specify the sender of the emails. If not specified on the command line, the value of the 'sendemail.from' configuration option is used. If - neither the command line option nor 'sendemail.from' are set, then the + neither the command-line option nor 'sendemail.from' are set, then the user will be prompted for the value. The default for the prompt will be the value of GIT_AUTHOR_IDENT, or GIT_COMMITTER_IDENT if that is not set, as returned by "git var -l". diff --git a/Documentation/git-svn.txt b/Documentation/git-svn.txt index fce5853..44c970c 100644 --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@ -148,8 +148,8 @@ the same local time zone. [verse] config key: svn-remote.<name>.ignore-paths + -If the ignore-paths config key is set and the command line option is -also given, both regular expressions will be used. +If the ignore-paths configuration key is set, and the command-line +option is also given, both regular expressions will be used. + Examples: + diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 0a0a551..c8f5ae5 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -68,7 +68,12 @@ performs all modifications together. Specify commands of the form: option SP <opt> LF Quote fields containing whitespace as if they were strings in C source -code. Alternatively, use `-z` to specify commands without quoting: +code; i.e., surrounded by double-quotes and with backslash escapes. +Use 40 "0" characters or the empty string to specify a zero value. To +specify a missing value, omit the value and its preceding SP entirely. + +Alternatively, use `-z` to specify in NUL-terminated format, without +quoting: update SP <ref> NUL <newvalue> NUL [<oldvalue>] NUL create SP <ref> NUL <newvalue> NUL @@ -76,8 +81,12 @@ code. Alternatively, use `-z` to specify commands without quoting: verify SP <ref> NUL [<oldvalue>] NUL option SP <opt> NUL -Lines of any other format or a repeated <ref> produce an error. -Command meanings are: +In this format, use 40 "0" to specify a zero value, and use the empty +string to specify a missing value. + +In either format, values can be specified in any form that Git +recognizes as an object name. Commands in any other format or a +repeated <ref> produce an error. Command meanings are: update:: Set <ref> to <newvalue> after verifying <oldvalue>, if given. @@ -102,9 +111,6 @@ option:: The only valid option is `no-deref` to avoid dereferencing a symbolic ref. -Use 40 "0" or the empty string to specify a zero value, except that -with `-z` an empty <oldvalue> is considered missing. - If all <ref>s can be locked with matching <oldvalue>s simultaneously, all modifications are performed. Otherwise, no modifications are performed. Note that while each individual diff --git a/Documentation/git-web--browse.txt b/Documentation/git-web--browse.txt index 2de575f..16ede5b 100644 --- a/Documentation/git-web--browse.txt +++ b/Documentation/git-web--browse.txt @@ -62,7 +62,7 @@ CONF.VAR (from -c option) and web.browser ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The web browser can be specified using a configuration variable passed -with the -c (or --config) command line option, or the 'web.browser' +with the -c (or --config) command-line option, or the 'web.browser' configuration variable if the former is not used. browser.<tool>.path @@ -87,7 +87,7 @@ the URLs passed as arguments. Note about konqueror -------------------- -When 'konqueror' is specified by a command line option or a +When 'konqueror' is specified by a command-line option or a configuration variable, we launch 'kfmclient' to try to open the HTML man page on an already opened konqueror in a new tab if possible. diff --git a/Documentation/git.txt b/Documentation/git.txt index b075e0b..3bd68b0 100644 --- a/Documentation/git.txt +++ b/Documentation/git.txt @@ -29,7 +29,7 @@ in-depth introduction. After you mastered the basic concepts, you can come back to this page to learn what commands Git offers. You can learn more about individual Git commands with "git help command". linkgit:gitcli[7] -manual page gives you an overview of the command line command syntax. +manual page gives you an overview of the command-line command syntax. Formatted and hyperlinked version of the latest Git documentation can be viewed at `http://git-htmldocs.googlecode.com/git/git.html`. @@ -39,7 +39,7 @@ ifdef::stalenotes[] ============ You are reading the documentation for the latest (possibly -unreleased) version of Git, that is available from 'master' +unreleased) version of Git, that is available from the 'master' branch of the `git.git` repository. Documentation for older releases are available here: @@ -755,7 +755,7 @@ Git so take care if using Cogito etc. 'GIT_WORK_TREE':: Set the path to the root of the working tree. - This can also be controlled by the '--work-tree' command line + This can also be controlled by the '--work-tree' command-line option and the core.worktree configuration variable. 'GIT_NAMESPACE':: @@ -880,7 +880,7 @@ 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 + 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]. diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt index 1c3e109..dfe7d83 100644 --- a/Documentation/gitcli.txt +++ b/Documentation/gitcli.txt @@ -3,7 +3,7 @@ gitcli(7) NAME ---- -gitcli - Git command line interface and conventions +gitcli - Git command-line interface and conventions SYNOPSIS -------- @@ -66,13 +66,13 @@ you will. Here are the rules regarding the "flags" that you should follow when you are scripting Git: - * it's preferred to use the non dashed form of Git commands, which means that + * it's preferred to use the non-dashed form of Git commands, which means that you should prefer `git foo` to `git-foo`. * splitting short options to separate words (prefer `git foo -a -b` to `git foo -ab`, the latter may not even work). - * when a command line option takes an argument, use the 'stuck' form. In + * when a command-line option takes an argument, use the 'stuck' form. In other words, write `git foo -oArg` instead of `git foo -o Arg` for short options, and `git foo --long-opt=Arg` instead of `git foo --long-opt Arg` for long options. An option that takes optional option-argument must be @@ -103,7 +103,7 @@ Here is a list of the facilities provided by this option parser. Magic Options ~~~~~~~~~~~~~ Commands which have the enhanced option parser activated all understand a -couple of magic command line options: +couple of magic command-line options: -h:: gives a pretty printed usage of the command. diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index 7e03fcc..7ae50aa 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -27,7 +27,7 @@ gitk-specific options. gitk generally only understands options with arguments in the 'sticked' form (see linkgit:gitcli[7]) due to limitations in the -command line parser. +command-line parser. rev-list options and arguments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/Documentation/gitmodules.txt b/Documentation/gitmodules.txt index 347a9f7..f6c0dfd 100644 --- a/Documentation/gitmodules.txt +++ b/Documentation/gitmodules.txt @@ -67,7 +67,9 @@ submodule.<name>.fetchRecurseSubmodules:: submodule.<name>.ignore:: Defines under what circumstances "git status" and the diff family show a submodule as modified. When set to "all", it will never be considered - modified, "dirty" will ignore all changes to the submodules work tree and + modified (but will nonetheless show up in the output of status and + commit when it has been staged), "dirty" will ignore all changes + to the submodules work tree and takes only differences between the HEAD of the submodule and the commit recorded in the superproject into account. "untracked" will additionally let submodules with modified tracked files in their work tree show up. diff --git a/Documentation/gitweb.conf.txt b/Documentation/gitweb.conf.txt index 952f503..ebe7a6c 100644 --- a/Documentation/gitweb.conf.txt +++ b/Documentation/gitweb.conf.txt @@ -904,7 +904,7 @@ the following in your GITWEB_CONFIG file: $feature{'snapshot'}{'override'} = 1; If you allow overriding for the snapshot feature, you can specify which -snapshot formats are globally disabled. You can also add any command line +snapshot formats are globally disabled. You can also add any command-line options you want (such as setting the compression level). For instance, you can disable Zip compressed snapshots and set *gzip*(1) to run at level 6 by adding the following lines to your gitweb configuration file: diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt index be0858c..4e0b971 100644 --- a/Documentation/glossary-content.txt +++ b/Documentation/glossary-content.txt @@ -1,7 +1,7 @@ [[def_alternate_object_database]]alternate object database:: Via the alternates mechanism, a <<def_repository,repository>> can inherit part of its <<def_object_database,object database>> - from another object database, which is called "alternate". + from another object database, which is called an "alternate". [[def_bare_repository]]bare repository:: A bare repository is normally an appropriately diff --git a/Documentation/howto/keep-canonical-history-correct.txt b/Documentation/howto/keep-canonical-history-correct.txt new file mode 100644 index 0000000..35d48ef --- /dev/null +++ b/Documentation/howto/keep-canonical-history-correct.txt @@ -0,0 +1,216 @@ +From: Junio C Hamano <gitster@pobox.com> +Date: Wed, 07 May 2014 13:15:39 -0700 +Subject: Beginner question on "Pull is mostly evil" +Abstract: This how-to explains a method for keeping a + project's history correct when using git pull. +Content-type: text/asciidoc + +Keep authoritative canonical history correct with git pull +========================================================== + +Sometimes a new project integrator will end up with project history +that appears to be "backwards" from what other project developers +expect. This howto presents a suggested integration workflow for +maintaining a central repository. + +Suppose that that central repository has this history: + +------------ + ---o---o---A +------------ + +which ends at commit `A` (time flows from left to right and each node +in the graph is a commit, lines between them indicating parent-child +relationship). + +Then you clone it and work on your own commits, which leads you to +have this history in *your* repository: + +------------ + ---o---o---A---B---C +------------ + +Imagine your coworker did the same and built on top of `A` in *his* +repository in the meantime, and then pushed it to the +central repository: + +------------ + ---o---o---A---X---Y---Z +------------ + +Now, if you `git push` at this point, because your history that leads +to `C` lacks `X`, `Y` and `Z`, it will fail. You need to somehow make +the tip of your history a descendant of `Z`. + +One suggested way to solve the problem is "fetch and then merge", aka +`git pull`. When you fetch, your repository will have a history like +this: + +------------ + ---o---o---A---B---C + \ + X---Y---Z +------------ + +Once you run merge after that, while still on *your* branch, i.e. `C`, +you will create a merge `M` and make the history look like this: + +------------ + ---o---o---A---B---C---M + \ / + X---Y---Z +------------ + +`M` is a descendant of `Z`, so you can push to update the central +repository. Such a merge `M` does not lose any commit in both +histories, so in that sense it may not be wrong, but when people want +to talk about "the authoritative canonical history that is shared +among the project participants", i.e. "the trunk", they often view +it as "commits you see by following the first-parent chain", and use +this command to view it: + +------------ + $ git log --first-parent +------------ + +For all other people who observed the central repository after your +coworker pushed `Z` but before you pushed `M`, the commit on the trunk +used to be `o-o-A-X-Y-Z`. But because you made `M` while you were on +`C`, `M`'s first parent is `C`, so by pushing `M` to advance the +central repository, you made `X-Y-Z` a side branch, not on the trunk. + +You would rather want to have a history of this shape: + +------------ + ---o---o---A---X---Y---Z---M' + \ / + B-----------C +------------ + +so that in the first-parent chain, it is clear that the project first +did `X` and then `Y` and then `Z` and merged a change that consists of +two commits `B` and `C` that achieves a single goal. You may have +worked on fixing the bug #12345 with these two patches, and the merge +`M'` with swapped parents can say in its log message "Merge +fix-bug-12345". Having a way to tell `git pull` to create a merge +but record the parents in reverse order may be a way to do so. + +Note that I said "achieves a single goal" above, because this is +important. "Swapping the merge order" only covers a special case +where the project does not care too much about having unrelated +things done on a single merge but cares a lot about first-parent +chain. + +There are multiple schools of thought about the "trunk" management. + + 1. Some projects want to keep a completely linear history without any + merges. Obviously, swapping the merge order would not match their + taste. You would need to flatten your history on top of the + updated upstream to result in a history of this shape instead: ++ +------------ + ---o---o---A---X---Y---Z---B---C +------------ ++ +with `git pull --rebase` or something. + + 2. Some projects tolerate merges in their history, but do not worry + too much about the first-parent order, and allow fast-forward + merges. To them, swapping the merge order does not hurt, but + it is unnecessary. + + 3. Some projects want each commit on the "trunk" to do one single + thing. The output of `git log --first-parent` in such a project + would show either a merge of a side branch that completes a single + theme, or a single commit that completes a single theme by itself. + If your two commits `B` and `C` (or they may even be two groups of + commits) were solving two independent issues, then the merge `M'` + we made in the earlier example by swapping the merge order is + still not up to the project standard. It merges two unrelated + efforts `B` and `C` at the same time. + +For projects in the last category (Git itself is one of them), +individual developers would want to prepare a history more like +this: + +------------ + C0--C1--C2 topic-c + / + ---o---o---A master + \ + B0--B1--B2 topic-b +------------ + +That is, keeping separate topics on separate branches, perhaps like +so: + +------------ + $ git clone $URL work && cd work + $ git checkout -b topic-b master + $ ... work to create B0, B1 and B2 to complete one theme + $ git checkout -b topic-c master + $ ... same for the theme of topic-c +------------ + +And then + +------------ + $ git checkout master + $ git pull --ff-only +------------ + +would grab `X`, `Y` and `Z` from the upstream and advance your master +branch: + +------------ + C0--C1--C2 topic-c + / + ---o---o---A---X---Y---Z master + \ + B0--B1--B2 topic-b +------------ + +And then you would merge these two branches separately: + +------------ + $ git merge topic-b + $ git merge topic-c +------------ + +to result in + +------------ + C0--C1---------C2 + / \ + ---o---o---A---X---Y---Z---M---N + \ / + B0--B1-----B2 +------------ + +and push it back to the central repository. + +It is very much possible that while you are merging topic-b and +topic-c, somebody again advanced the history in the central repository +to put `W` on top of `Z`, and make your `git push` fail. + +In such a case, you would rewind to discard `M` and `N`, update the +tip of your 'master' again and redo the two merges: + +------------ + $ git reset --hard origin/master + $ git pull --ff-only + $ git merge topic-b + $ git merge topic-c +------------ + +The procedure will result in a history that looks like this: + +------------ + C0--C1--------------C2 + / \ + ---o---o---A---X---Y---Z---W---M'--N' + \ / + B0--B1---------B2 +------------ + +See also http://git-blame.blogspot.com/2013/09/fun-with-first-parent-history.html diff --git a/Documentation/howto/setup-git-server-over-http.txt b/Documentation/howto/setup-git-server-over-http.txt index 6de4f3c..f44e5e9 100644 --- a/Documentation/howto/setup-git-server-over-http.txt +++ b/Documentation/howto/setup-git-server-over-http.txt @@ -181,7 +181,7 @@ On Debian: Most tests should pass. -A command line tool to test WebDAV is cadaver. If you prefer GUIs, for +A command-line tool to test WebDAV is cadaver. If you prefer GUIs, for example, konqueror can open WebDAV URLs as "webdav://..." or "webdavs://...". diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt index 5a286d0..0796118 100644 --- a/Documentation/revisions.txt +++ b/Documentation/revisions.txt @@ -94,7 +94,9 @@ some output processing may assume ref names in UTF-8. '<branchname>@\{upstream\}', e.g. 'master@\{upstream\}', '@\{u\}':: The suffix '@\{upstream\}' to a branchname (short form '<branchname>@\{u\}') refers to the branch that the branch specified by branchname is set to build on - top of. A missing branchname defaults to the current one. + top of (configured with `branch.<name>.remote` and + `branch.<name>.merge`). A missing branchname defaults to the + current one. '<rev>{caret}', e.g. 'HEAD{caret}, v1.5.1{caret}0':: A suffix '{caret}' to a revision parameter means the first parent of diff --git a/Documentation/technical/api-argv-array.txt b/Documentation/technical/api-argv-array.txt index a6b7d83..1a79781 100644 --- a/Documentation/technical/api-argv-array.txt +++ b/Documentation/technical/api-argv-array.txt @@ -53,11 +53,3 @@ Functions `argv_array_clear`:: Free all memory associated with the array and return it to the initial, empty state. - -`argv_array_detach`:: - Detach the argv array from the `struct argv_array`, transferring - ownership of the allocated array and strings. - -`argv_array_free_detached`:: - Free the memory allocated by a `struct argv_array` that was later - detached and is now no longer needed. diff --git a/Documentation/technical/api-builtin.txt b/Documentation/technical/api-builtin.txt index e3d6e7a..22a39b9 100644 --- a/Documentation/technical/api-builtin.txt +++ b/Documentation/technical/api-builtin.txt @@ -22,11 +22,14 @@ Git: where options is the bitwise-or of: `RUN_SETUP`:: - - Make sure there is a Git directory to work on, and if there is a - work tree, chdir to the top of it if the command was invoked - in a subdirectory. If there is no work tree, no chdir() is - done. + If there is not a Git directory to work on, abort. If there + is a work tree, chdir to the top of it if the command was + invoked in a subdirectory. If there is no work tree, no + chdir() is done. + +`RUN_SETUP_GENTLY`:: + If there is a Git directory, chdir as per RUN_SETUP, otherwise, + don't chdir anywhere. `USE_PAGER`:: diff --git a/Documentation/technical/api-run-command.txt b/Documentation/technical/api-run-command.txt index 5d7d7f2..69510ae 100644 --- a/Documentation/technical/api-run-command.txt +++ b/Documentation/technical/api-run-command.txt @@ -109,6 +109,13 @@ terminated), of which .argv[0] is the program name to run (usually without a path). If the command to run is a git command, set argv[0] to the command name without the 'git-' prefix and set .git_cmd = 1. +Note that the ownership of the memory pointed to by .argv stays with the +caller, but it should survive until `finish_command` completes. If the +.argv member is NULL, `start_command` will point it at the .args +`argv_array` (so you may use one or the other, but you must use exactly +one). The memory in .args will be cleaned up automatically during +`finish_command` (or during `start_command` when it is unsuccessful). + The members .in, .out, .err are used to redirect stdin, stdout, stderr as follows: diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index 1d00e4d..f9c06a7 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -121,10 +121,28 @@ Functions * Related to the contents of the buffer +`strbuf_trim`:: + + Strip whitespace from the beginning and end of a string. + Equivalent to performing `strbuf_rtrim()` followed by `strbuf_ltrim()`. + `strbuf_rtrim`:: Strip whitespace from the end of a string. +`strbuf_ltrim`:: + + Strip whitespace from the beginning of a string. + +`strbuf_reencode`:: + + Replace the contents of the strbuf with a reencoded form. Returns -1 + on error, 0 on success. + +`strbuf_tolower`:: + + Lowercase each character in the buffer using `tolower`. + `strbuf_cmp`:: Compare two buffers. Returns an integer less than, equal to, or greater diff --git a/Documentation/technical/api-string-list.txt b/Documentation/technical/api-string-list.txt index 20be348..f1add51 100644 --- a/Documentation/technical/api-string-list.txt +++ b/Documentation/technical/api-string-list.txt @@ -200,3 +200,5 @@ Represents the list itself. You should not tamper with it. . Setting the `strdup_strings` member to 1 will strdup() the strings before adding them, see above. +. The `compare_strings_fn` member is used to specify a custom compare + function, otherwise `strcmp()` is used as the default function. diff --git a/Documentation/technical/http-protocol.txt b/Documentation/technical/http-protocol.txt index 20525d9..59be59b 100644 --- a/Documentation/technical/http-protocol.txt +++ b/Documentation/technical/http-protocol.txt @@ -374,7 +374,7 @@ C: Send one `$GIT_URL/git-upload-pack` request: C: 0000 The stream is organized into "commands", with each command -appearing by itself in a pkt-line. Within a command line +appearing by itself in a pkt-line. Within a command line, the text leading up to the first space is the command name, and the remainder of the line to the first LF is the value. Command lines are terminated with an LF as the last byte of diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 022e74e..7330d88 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -416,12 +416,11 @@ REVISIONS" section of linkgit:gitrevisions[7]. Updating a repository with git fetch ------------------------------------ -Eventually the developer cloned from will do additional work in her -repository, creating new commits and advancing the branches to point -at the new commits. +After you clone a repository and commit a few changes of your own, you +may wish to check the original repository for updates. -The command `git fetch`, with no arguments, will update all of the -remote-tracking branches to the latest version found in her +The `git-fetch` command, with no arguments, will update all of the +remote-tracking branches to the latest version found in the original repository. It will not touch any of your own branches--not even the "master" branch that was created for you on clone. @@ -1811,8 +1810,8 @@ manner. You can then import these into your mail client and send them by hand. However, if you have a lot to send at once, you may prefer to use the linkgit:git-send-email[1] script to automate the process. -Consult the mailing list for your project first to determine how they -prefer such patches be handled. +Consult the mailing list for your project first to determine +their requirements for submitting patches. [[importing-patches]] Importing patches to a project @@ -2255,7 +2254,7 @@ $ git checkout test && git merge speed-up-spinlocks It is unlikely that you would have any conflicts here ... but you might if you spent a while on this step and had also pulled new versions from upstream. -Some time later when enough time has passed and testing done, you can pull the +Sometime later when enough time has passed and testing done, you can pull the same branch into the `release` tree ready to go upstream. This is where you see the value of keeping each patch (or patch series) in its own branch. It means that the patches can be moved into the `release` tree in any order. @@ -4231,9 +4230,9 @@ Most of what `git rev-list` did is contained in `revision.c` and controls how and what revisions are walked, and more. The original job of `git rev-parse` is now taken by the function -`setup_revisions()`, which parses the revisions and the common command line +`setup_revisions()`, which parses the revisions and the common command-line options for the revision walker. This information is stored in the struct -`rev_info` for later consumption. You can do your own command line option +`rev_info` for later consumption. You can do your own command-line option parsing after calling `setup_revisions()`. After that, you have to call `prepare_revision_walk()` for initialization, and then you can get the commits one by one with the function `get_revision()`. |