diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/CodingGuidelines | 12 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.10.txt | 67 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.8.5.txt | 19 | ||||
| -rw-r--r-- | Documentation/RelNotes/1.7.9.3.txt | 24 | ||||
| -rw-r--r-- | Documentation/config.txt | 12 | ||||
| -rw-r--r-- | Documentation/git-config.txt | 7 | ||||
| -rw-r--r-- | Documentation/git-p4.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-push.txt | 10 | ||||
| -rw-r--r-- | Documentation/git-send-email.txt | 4 | ||||
| -rw-r--r-- | Documentation/gitattributes.txt | 41 | ||||
| -rw-r--r-- | Documentation/merge-options.txt | 22 | ||||
| -rw-r--r-- | Documentation/rev-list-options.txt | 12 | ||||
| -rw-r--r-- | Documentation/technical/api-parse-options.txt | 3 | ||||
| -rw-r--r-- | Documentation/technical/api-strbuf.txt | 18 |
14 files changed, 208 insertions, 53 deletions
diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 483008699f..45577117c2 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -35,10 +35,22 @@ For shell scripts specifically (not exhaustive): - Case arms are indented at the same depth as case and esac lines. + - Redirection operators should be written with space before, but no + space after them. In other words, write 'echo test >"$file"' + instead of 'echo test> $file' or 'echo test > $file'. Note that + even though it is not required by POSIX to double-quote the + redirection target in a variable (as shown above), our code does so + because some versions of bash issue a warning without the quotes. + - 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. + - If you want to find out if a command is available on the user's + $PATH, you should use 'type <command>', instead of 'which <command>'. + The output of 'which' is not machine parseable and its exit code + is not reliable across platforms. + - We use POSIX compliant parameter substitutions and avoid bashisms; namely: diff --git a/Documentation/RelNotes/1.7.10.txt b/Documentation/RelNotes/1.7.10.txt index 0add762b0a..071e40c59b 100644 --- a/Documentation/RelNotes/1.7.10.txt +++ b/Documentation/RelNotes/1.7.10.txt @@ -6,6 +6,11 @@ Updates since v1.7.9 UI, Workflows & Features + * Teams for localizing the messages from the Porcelain layer of + commands are starting to form, thanks to Jiang Xin who volunteered + to be the localization coordinator. An initial set of translated + messages for simplified chinese is available. + * Improved handling of views, labels and branches in git-p4 (in contrib). * "git-p4" (in contrib) suffered from unnecessary merge conflicts when @@ -22,6 +27,10 @@ UI, Workflows & Features file to be included in-place when Git looks up configuration variables. + * A content filter (clean/smudge) used to be just a way to make the + recorded contents "more useful", and allowed to fail; a filter can + new optionally be marked as "required". + * "git am" learned to pass "-b" option to underlying "git mailinfo", so that bracketed string other than "PATCH" at the beginning can be kept. @@ -38,23 +47,30 @@ UI, Workflows & Features * "diff-highlight" filter (in contrib/) was updated to produce more aesthetically pleasing output. - * "git tag --list" can be given "--points-at <object>" to limit its - output to those that point at the given object. - * "git merge" in an interactive session learned to spawn the editor by default to let the user edit the auto-generated merge message, to encourage people to explain their merges better. Legacy scripts - can export MERGE_AUTOEDIT=no to retain the historical behaviour. + can export GIT_MERGE_AUTOEDIT=no to retain the historical behavior. Both "git merge" and "git pull" can be given --no-edit from the command line to accept the auto-generated merge message. + * "git push" learned the "--prune" option, similar to "git fetch". + + * "git tag --list" can be given "--points-at <object>" to limit its + output to those that point at the given object. + * "gitweb" allows intermediate entries in the directory hierarchy that leads to a projects to be clicked, which in turn shows the list of projects inside that directory. + * "gitweb" learned to read various pieces of information for the + repositories lazily, instead of reading everything that could be + needed (including the ones that are not necessary for a specific + task). + Performance - * During "git upload-pack" in respose to "git fetch", unnecessary calls + * During "git upload-pack" in response to "git fetch", unnecessary calls to parse_object() have been eliminated, to help performance in repositories with excessive number of refs. @@ -87,14 +103,39 @@ Unless otherwise noted, all the fixes since v1.7.9 in the maintenance releases are contained in this release (see release notes to them for details). - * The config.mak.autogen generated by optional autoconf support tried - to link the binary with -lintl even when libintl.h is missing from - the system. - (merge a8356d4 js/configure-libintl later to maint). + * "git branch --with $that" assumed incorrectly that the user will never + ask the question with nonsense value in $that. + (merge 6c41e97 cn/maint-branch-with-bad later to maint). + + * An invalid regular expression pattern given by an end user made + "gitweb" to return garbled response. + (merge 36612e4 jn/maint-gitweb-invalid-regexp later to maint). + + * "git rev-list --verify-objects -q" omitted the extra verification + it needs to do over "git rev-list --objects -q" by mistake. + (merge 9899372 nd/maint-verify-objects later to maint). + + * The bulk check-in codepath streamed contents that needs + smudge/clean filters without running them, instead of punting and + delegating to the codepath to run filters after slurping everything + to core. + (merge 4f22b10 jk/maint-avoid-streaming-filtered-contents later to maint). + + * When the filter driver exits before reading the content before the + main git process writes the contents to be filtered to the pipe to + it, the latter could be killed with SIGPIPE instead of ignoring + such an event as an error. + (merge 6424c2a jb/filter-ignore-sigpipe later to maint). + + * When a remote helper exits before reading the blank line from the + main git process to signal the end of commands, the latter could be + killed with SIGPIPE. Instead we should ignore such event as a + non-error. + (merge c34fe63 sp/smart-http-failure-to-push later to maint). - * "git add --refresh <pathspec>" used to warn about unmerged paths - outside the given pathspec. - (merge 3d1f148 jc/add-refresh-unmerged later to maint). + * "git bundle create" produced a corrupt bundle file upon seeing + commits with excessively long subject line. + (merge 8a557bb tr/maint-bundle-long-subject later to maint). * "gitweb" used to drop warnings in the log file when "heads" view is accessed in a repository whose HEAD does not point at a valid @@ -102,7 +143,7 @@ details). --- exec >/var/tmp/1 -O=v1.7.9.2-261-gd065f68 +O=v1.7.9.2-347-gbfabdfe echo O=$(git describe) git log --first-parent --oneline ^maint $O.. echo diff --git a/Documentation/RelNotes/1.7.8.5.txt b/Documentation/RelNotes/1.7.8.5.txt new file mode 100644 index 0000000000..011fd2a428 --- /dev/null +++ b/Documentation/RelNotes/1.7.8.5.txt @@ -0,0 +1,19 @@ +Git v1.7.8.5 Release Notes +========================== + +Fixes since v1.7.8.4 +-------------------- + + * Dependency on our thread-utils.h header file was missing for + objects that depend on it in the Makefile. + + * "git am" when fed an empty file did not correctly finish reading it + when it attempts to guess the input format. + + * "git grep -P" (when PCRE is enabled in the build) did not match the + beginning and the end of the line correctly with ^ and $. + + * "git rebase -m" tried to run "git notes copy" needlessly when + nothing was rewritten. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/RelNotes/1.7.9.3.txt b/Documentation/RelNotes/1.7.9.3.txt new file mode 100644 index 0000000000..d7be177681 --- /dev/null +++ b/Documentation/RelNotes/1.7.9.3.txt @@ -0,0 +1,24 @@ +Git v1.7.9.3 Release Notes +========================== + +Fixes since v1.7.9.2 +-------------------- + + * "git p4" (in contrib/) submit the changes to a wrong place when the + "--use-client-spec" option is set. + + * The config.mak.autogen generated by optional autoconf support tried + to link the binary with -lintl even when libintl.h is missing from + the system. + + * "git add --refresh <pathspec>" used to warn about unmerged paths + outside the given pathspec. + + * The commit log template given with "git merge --edit" did not have + a short instructive text like what "git commit" gives. + + * "gitweb" used to drop warnings in the log file when "heads" view is + accessed in a repository whose HEAD does not point at a valid + branch. + +Also contains minor fixes and documentation updates. diff --git a/Documentation/config.txt b/Documentation/config.txt index e55dae1806..5367ba9cae 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -12,8 +12,9 @@ The configuration variables are used by both the git plumbing and the porcelains. The variables are divided into sections, wherein the fully qualified variable name of the variable itself is the last dot-separated segment and the section name is everything before the last -dot. The variable names are case-insensitive and only alphanumeric -characters are allowed. Some variables may appear multiple times. +dot. The variable names are case-insensitive, allow only alphanumeric +characters and `-`, and must start with an alphabetic character. Some +variables may appear multiple times. Syntax ~~~~~~ @@ -54,9 +55,10 @@ All the other lines (and the remainder of the line after the section header) are recognized as setting variables, in the form 'name = value'. If there is no equal sign on the line, the entire line is taken as 'name' and the variable is recognized as boolean "true". -The variable names are case-insensitive and only alphanumeric -characters and `-` are allowed. There can be more than one value -for a given variable; we say then that variable is multivalued. +The variable names are case-insensitive, allow only alphanumeric characters +and `-`, and must start with an alphabetic character. There can be more +than one value for a given variable; we say then that the variable is +multivalued. Leading and trailing whitespace in a variable value is discarded. Internal whitespace within a variable value is retained verbatim. diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index aa8303b1ad..81b03982e3 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -85,8 +85,11 @@ OPTIONS is not exactly one. --get-regexp:: - Like --get-all, but interprets the name as a regular expression. - Also outputs the key names. + Like --get-all, but interprets the name as a regular expression and + writes out the key names. Regular expression matching is currently + case-sensitive and done against a canonicalized version of the key + in which section and variable names are lowercased, but subsection + names are not. --global:: For writing options: write to global ~/.gitconfig file rather than diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index 3fecefaea2..b7c7929716 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -303,9 +303,13 @@ CLIENT SPEC ----------- The p4 client specification is maintained with the 'p4 client' command and contains among other fields, a View that specifies how the depot -is mapped into the client repository. Git-p4 can consult the client -spec when given the '--use-client-spec' option or useClientSpec -variable. +is mapped into the client repository. The 'clone' and 'sync' commands +can consult the client spec when given the '--use-client-spec' option or +when the useClientSpec variable is true. After 'git p4 clone', the +useClientSpec variable is automatically set in the repository +configuration file. This allows future 'git p4 submit' commands to +work properly; the submit command looks only at the variable and does +not have a command-line option. The full syntax for a p4 view is documented in 'p4 help views'. Git-p4 knows only a subset of the view syntax. It understands multi-line diff --git a/Documentation/git-push.txt b/Documentation/git-push.txt index aede48877f..48760db337 100644 --- a/Documentation/git-push.txt +++ b/Documentation/git-push.txt @@ -10,7 +10,7 @@ SYNOPSIS -------- [verse] 'git push' [--all | --mirror | --tags] [-n | --dry-run] [--receive-pack=<git-receive-pack>] - [--repo=<repository>] [-f | --force] [-v | --verbose] [-u | --set-upstream] + [--repo=<repository>] [-f | --force] [--prune] [-v | --verbose] [-u | --set-upstream] [<repository> [<refspec>...]] DESCRIPTION @@ -71,6 +71,14 @@ nor in any Push line of the corresponding remotes file---see below). Instead of naming each ref to push, specifies that all refs under `refs/heads/` be pushed. +--prune:: + Remove remote branches that don't have a local counterpart. For example + a remote branch `tmp` will be removed if a local branch with the same + name doesn't exist any more. This also respects refspecs, e.g. + `git push --prune remote refs/heads/{asterisk}:refs/tmp/{asterisk}` would + make sure that remote `refs/tmp/foo` will be removed if `refs/heads/foo` + doesn't exist. + --mirror:: Instead of naming each ref to push, specifies that all refs under `refs/` (which includes but is not diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt index 327233c85b..324117072d 100644 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@ -198,6 +198,10 @@ must be used for each option. if a username is not specified (with '--smtp-user' or 'sendemail.smtpuser'), then authentication is not attempted. +--smtp-debug=0|1:: + Enable (1) or disable (0) debug output. If enabled, SMTP + commands and replies will be printed. Useful to debug TLS + connection and authentication problems. Automating ~~~~~~~~~~ diff --git a/Documentation/gitattributes.txt b/Documentation/gitattributes.txt index a85b187e04..80120ea14f 100644 --- a/Documentation/gitattributes.txt +++ b/Documentation/gitattributes.txt @@ -294,16 +294,27 @@ output is used to update the worktree file. Similarly, the `clean` command is used to convert the contents of worktree file upon checkin. -A missing filter driver definition in the config is not an error -but makes the filter a no-op passthru. - -The content filtering is done to massage the content into a -shape that is more convenient for the platform, filesystem, and -the user to use. The key phrase here is "more convenient" and not -"turning something unusable into usable". In other words, the -intent is that if someone unsets the filter driver definition, -or does not have the appropriate filter program, the project -should still be usable. +One use of the content filtering is to massage the content into a shape +that is more convenient for the platform, filesystem, and the user to use. +For this mode of operation, the key phrase here is "more convenient" and +not "turning something unusable into usable". In other words, the intent +is that if someone unsets the filter driver definition, or does not have +the appropriate filter program, the project should still be usable. + +Another use of the content filtering is to store the content that cannot +be directly used in the repository (e.g. a UUID that refers to the true +content stored outside git, or an encrypted content) and turn it into a +usable form upon checkout (e.g. download the external content, or decrypt +the encrypted content). + +These two filters behave differently, and by default, a filter is taken as +the former, massaging the contents into more convenient shape. A missing +filter driver definition in the config, or a filter driver that exits with +a non-zero status, is not an error but makes the filter a no-op passthru. + +You can declare that a filter turns a content that by itself is unusable +into a usable content by setting the filter.<driver>.required configuration +variable to `true`. For example, in .gitattributes, you would assign the `filter` attribute for paths. @@ -335,6 +346,16 @@ input that is already correctly indented. In this case, the lack of a smudge filter means that the clean filter _must_ accept its own output without modifying it. +If a filter _must_ succeed in order to make the stored contents usable, +you can declare that the filter is `required`, in the configuration: + +------------------------ +[filter "crypt"] + clean = openssl enc ... + smudge = openssl enc -d ... + required +------------------------ + Sequence "%f" on the filter command line is replaced with the name of the file the filter is working on. A filter might use this in keyword substitution. For example: diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt index f2f1d0f51c..0bcbe0ac3c 100644 --- a/Documentation/merge-options.txt +++ b/Documentation/merge-options.txt @@ -24,13 +24,18 @@ updated behaviour, the environment variable `GIT_MERGE_AUTOEDIT` can be set to `no` at the beginning of them. --ff:: + When the merge resolves as a fast-forward, only update the branch + pointer, without creating a merge commit. This is the default + behavior. + --no-ff:: - Do not generate a merge commit if the merge resolved as - a fast-forward, only update the branch pointer. This is - the default behavior of git-merge. -+ -With --no-ff Generate a merge commit even if the merge -resolved as a fast-forward. + Create a merge commit even when the merge resolves as a + fast-forward. + +--ff-only:: + Refuse to merge and exit with a non-zero status unless the + current `HEAD` is already up-to-date or the merge can be + resolved as a fast-forward. --log[=<n>]:: --no-log:: @@ -65,11 +70,6 @@ merge. With --no-squash perform the merge and commit the result. This option can be used to override --squash. ---ff-only:: - Refuse to merge and exit with a non-zero status unless the - current `HEAD` is already up-to-date or the merge can be - resolved as a fast-forward. - -s <strategy>:: --strategy=<strategy>:: Use the given merge strategy; can be supplied more than diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index 39e6207269..6a4b6355ba 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -117,27 +117,27 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit). Pretend as if all the refs in `refs/heads` are listed on the command line as '<commit>'. If '<pattern>' is given, limit branches to ones matching given shell glob. If pattern lacks '?', - '*', or '[', '/*' at the end is implied. + '{asterisk}', or '[', '/{asterisk}' at the end is implied. --tags[=<pattern>]:: Pretend as if all the refs in `refs/tags` are listed on the command line as '<commit>'. If '<pattern>' is given, limit - tags to ones matching given shell glob. If pattern lacks '?', '*', - or '[', '/*' at the end is implied. + tags to ones matching given shell glob. If pattern lacks '?', '{asterisk}', + or '[', '/{asterisk}' at the end is implied. --remotes[=<pattern>]:: Pretend as if all the refs in `refs/remotes` are listed on the command line as '<commit>'. If '<pattern>' is given, limit remote-tracking branches to ones matching given shell glob. - If pattern lacks '?', '*', or '[', '/*' at the end is implied. + If pattern lacks '?', '{asterisk}', or '[', '/{asterisk}' at the end is implied. --glob=<glob-pattern>:: Pretend as if all the refs matching shell glob '<glob-pattern>' are listed on the command line as '<commit>'. Leading 'refs/', - is automatically prepended if missing. If pattern lacks '?', '*', - or '[', '/*' at the end is implied. + is automatically prepended if missing. If pattern lacks '?', '{asterisk}', + or '[', '/{asterisk}' at the end is implied. --ignore-missing:: diff --git a/Documentation/technical/api-parse-options.txt b/Documentation/technical/api-parse-options.txt index 4b92514f60..2527b7e8d7 100644 --- a/Documentation/technical/api-parse-options.txt +++ b/Documentation/technical/api-parse-options.txt @@ -39,7 +39,8 @@ The parse-options API allows: * Short options may be bundled, e.g. `-a -b` can be specified as `-ab`. * Boolean long options can be 'negated' (or 'unset') by prepending - `no-`, e.g. `\--no-abbrev` instead of `\--abbrev`. + `no-`, e.g. `\--no-abbrev` instead of `\--abbrev`. Conversely, + options that begin with `no-` can be 'negated' by removing it. * Options and non-option arguments can clearly be separated using the `\--` option, e.g. `-a -b \--option \-- \--this-is-a-file` indicates that diff --git a/Documentation/technical/api-strbuf.txt b/Documentation/technical/api-strbuf.txt index afe2759951..95a8bf3846 100644 --- a/Documentation/technical/api-strbuf.txt +++ b/Documentation/technical/api-strbuf.txt @@ -255,8 +255,24 @@ same behaviour as well. `strbuf_getline`:: - Read a line from a FILE* pointer. The second argument specifies the line + Read a line from a FILE *, overwriting the existing contents + of the strbuf. The second argument specifies the line terminator character, typically `'\n'`. + Reading stops after the terminator or at EOF. The terminator + is removed from the buffer before returning. Returns 0 unless + there was nothing left before EOF, in which case it returns `EOF`. + +`strbuf_getwholeline`:: + + Like `strbuf_getline`, but keeps the trailing terminator (if + any) in the buffer. + +`strbuf_getwholeline_fd`:: + + Like `strbuf_getwholeline`, but operates on a file descriptor. + It reads one character at a time, so it is very slow. Do not + use it unless you need the correct position in the file + descriptor. `stripspace`:: |