diff options
Diffstat (limited to 'Documentation')
38 files changed, 772 insertions, 103 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index f424dbd75c..4d90c77c7b 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 fc6b2cf9ec..cea0e7ae3d 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/1.9.4.txt b/Documentation/RelNotes/1.9.4.txt new file mode 100644 index 0000000000..e1d1835436 --- /dev/null +++ b/Documentation/RelNotes/1.9.4.txt @@ -0,0 +1,16 @@ +Git v1.9.4 Release Notes +======================== + +Fixes since v1.9.3 +------------------ + + * Commands that take pathspecs on the command line misbehaved when + the pathspec is given as an absolute pathname (which is a + practice not particularly encouraged) that points at a symbolic + link in the working tree. + + * An earlier fix to the shell prompt script (in contrib/) for using + the PROMPT_COMMAND interface did not correctly check if the extra + code path needs to trigger, causing the branch name not to appear + when 'promptvars' option is disabled in bash or PROMPT_SUBST is + unset in zsh. diff --git a/Documentation/RelNotes/2.0.0.txt b/Documentation/RelNotes/2.0.0.txt index b7da746add..2617372a0c 100644 --- a/Documentation/RelNotes/2.0.0.txt +++ b/Documentation/RelNotes/2.0.0.txt @@ -55,8 +55,9 @@ UI, Workflows & Features * The "multi-mail" post-receive hook (in contrib/) has been updated to a more recent version from upstream. - * The "remote-hg/bzr" remote-helper interfaces (in contrib/) are - now maintained separately as a third-party plug-in. + * The "remote-hg/bzr" remote-helper interfaces (used to be in + contrib/) are no more. They are now maintained separately as + third-party plug-ins in their own repositories. * "git gc --aggressive" learned "--depth" option and "gc.aggressiveDepth" configuration variable to allow use of a less @@ -190,12 +191,7 @@ notes for details). * The shell prompt script (in contrib/), when using the PROMPT_COMMAND interface, used an unsafe construct when showing the branch name in $PS1. - (merge 8976500 rh/prompt-pcmode-avoid-eval-on-refname later to maint). - - * The remote-helper interface to fast-import/fast-export via the - transport-helper has been tightened to avoid leaving the import - marks file from a failed/crashed run, as such a file that is out-of- - sync with reality confuses a later invocation of itself. + (merge 1e4119c8 rh/prompt-pcmode-avoid-eval-on-refname later to maint). * "git rebase" used a POSIX shell construct FreeBSD's /bin/sh does not work well with. @@ -344,7 +340,7 @@ notes for details). the pathspec is given as an absolute pathname (which is a practice not particularly encouraged) that points at a symbolic link in the working tree. - (merge later 655ee9e mw/symlinks to maint.) + (merge 6127ff6 mw/symlinks later to maint.) * "git diff --quiet -- pathspec1 pathspec2" sometimes did not return the correct status value. diff --git a/Documentation/RelNotes/2.1.0.txt b/Documentation/RelNotes/2.1.0.txt new file mode 100644 index 0000000000..5974734bb4 --- /dev/null +++ b/Documentation/RelNotes/2.1.0.txt @@ -0,0 +1,200 @@ +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. + + * "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 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 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 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. + + +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). + + * "--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 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 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 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). + + * "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 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 140ed771ef..20cb3a25bc 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 @@ -1328,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 @@ -2297,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. @@ -2321,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 f07b4513ed..b001779520 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 f986c5cb3a..4cb52a7302 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 e9917b89a9..9dfa1a5ce2 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' |