diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/RelNotes/2.30.0.txt | 77 | ||||
| -rw-r--r-- | Documentation/blame-options.txt | 9 | ||||
| -rw-r--r-- | Documentation/config.txt | 2 | ||||
| -rw-r--r-- | Documentation/config/format.txt | 5 | ||||
| -rw-r--r-- | Documentation/config/maintenance.txt | 25 | ||||
| -rw-r--r-- | Documentation/diff-options.txt | 17 | ||||
| -rw-r--r-- | Documentation/git-blame.txt | 4 | ||||
| -rw-r--r-- | Documentation/git-branch.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-for-each-repo.txt | 59 | ||||
| -rw-r--r-- | Documentation/git-format-patch.txt | 8 | ||||
| -rw-r--r-- | Documentation/git-grep.txt | 6 | ||||
| -rw-r--r-- | Documentation/git-log.txt | 15 | ||||
| -rw-r--r-- | Documentation/git-ls-files.txt | 5 | ||||
| -rw-r--r-- | Documentation/git-ls-tree.txt | 3 | ||||
| -rw-r--r-- | Documentation/git-maintenance.txt | 99 | ||||
| -rw-r--r-- | Documentation/git-p4.txt | 2 | ||||
| -rw-r--r-- | Documentation/git-rev-parse.txt | 8 | ||||
| -rw-r--r-- | Documentation/githooks.txt | 2 | ||||
| -rw-r--r-- | Documentation/gitk.txt | 20 | ||||
| -rw-r--r-- | Documentation/line-range-format.txt | 28 | ||||
| -rw-r--r-- | Documentation/line-range-options.txt | 15 | ||||
| -rw-r--r-- | Documentation/pretty-options.txt | 6 |
22 files changed, 350 insertions, 73 deletions
diff --git a/Documentation/RelNotes/2.30.0.txt b/Documentation/RelNotes/2.30.0.txt index 76ae487fe9..4c5be2dd04 100644 --- a/Documentation/RelNotes/2.30.0.txt +++ b/Documentation/RelNotes/2.30.0.txt @@ -63,8 +63,18 @@ UI, Workflows & Features * Exit codes from "git remote add" etc. were not usable by scripted callers, but now they are. + * "git archive" now allows compression level higher than "-9" + when generating tar.gz output. + * Zsh autocompletion (in contrib/) update. + * The maximum length of output filenames "git format-patch" creates + has become configurable (used to be capped at 64). + + * "git rev-parse" learned the "--end-of-options" to help scripts to + safely take a parameter that is supposed to be a revision, e.g. + "git rev-parse --verify -q --end-of-options $rev". + Performance, Internal Implementation, Development Support etc. @@ -101,6 +111,11 @@ Performance, Internal Implementation, Development Support etc. * Test scripts are being prepared to transition of the default branch name to 'main'. + * "git fetch --depth=<n>" over the stateless RPC / smart HTTP + transport handled EOF from the client poorly at the server end. + + * A specialization of hashmap that uses a string as key has been + introduced. Hopefully it will see wider use over time. Fixes since v2.29 @@ -167,6 +182,61 @@ Fixes since v2.29 * A recent oid->hash conversion missed one spot, breaking "git svn". (merge 03bb366de4 bc/svn-hash-oid-fix later to maint). + * The documentation on the "--abbrev=<n>" option did not say the + output may be longer than "<n>" hexdigits, which has been + clarified. + (merge cda34e0d0c jc/abbrev-doc later to maint). + + * "git p4" now honors init.defaultBranch configuration. + (merge 1b09d1917f js/p4-default-branch later to maint). + + * Recently the format of an internal state file "rebase -i" uses has + been tightened up for consistency, which would hurt those who start + "rebase -i" with old git and then continue with new git. Loosen + the reader side a bit (which we may want to tighten again in a year + or so). + (merge c779386182 jc/sequencer-stopped-sha-simplify later to maint). + + * The code to see if "git stash drop" can safely remove refs/stash + has been made more carerful. + (merge 4f44c5659b rs/empty-reflog-check-fix later to maint). + + * "git log -L<range>:<path>" is documented to take no pathspec, but + this was not enforced by the command line option parser, which has + been corrected. + (merge 39664cb0ac jc/line-log-takes-no-pathspec later to maint). + + * "git format-patch --output=there" did not work as expected and + instead crashed. The option is now supported. + (merge dc1672dd10 jk/format-patch-output later to maint). + + * Define ARM64 compiled with MSVC to be little-endian. + (merge 0c038fc65a dg/bswap-msvc later to maint). + + * "git rebase -i" did not store ORIG_HEAD correctly. + (merge 8843302307 pw/rebase-i-orig-head later to maint). + + * "git blame -L :funcname -- path" did not work well for a path for + which a userdiff driver is defined. + + * "make DEVELOPER=1 sparse" used to run sparse and let it emit + warnings; now such warnings will cause an error. + (merge 521dc56270 jc/sparse-error-for-developer-build later to maint). + + * "git blame --ignore-revs-file=<file>" learned to ignore a + non-existent object name in the input, instead of complaining. + (merge c714d05875 jc/blame-ignore-fix later to maint). + + * Running "git diff" while allowing external diff in a state with + unmerged paths used to segfault, which has been corrected. + (merge d66851806f jk/diff-release-filespec-fix later to maint). + + * Build configuration cleanup. + (merge b990f02fd8 ab/config-mak-uname-simplify later to maint). + + * Fix regression introduced when nvimdiff support in mergetool was added. + (merge 12026f46e7 pd/mergetool-nvimdiff later to maint). + * Other code cleanup, docfix, build fix, etc. (merge 3e0a5dc9af cc/doc-filter-branch-typofix later to maint). (merge 32c83afc2c cw/ci-ghwf-check-ws-errors later to maint). @@ -177,3 +247,10 @@ Fixes since v2.29 (merge 9a82db1056 en/sequencer-rollback-lock-cleanup later to maint). (merge 4e1bee9a99 js/t7006-cleanup later to maint). (merge f5bcde6c58 es/tutorial-mention-asciidoc-early later to maint). + (merge 714d491af0 so/format-patch-doc-on-default-diff-format later to maint). + (merge 0795df4b9b rs/clear-commit-marks-in-repo later to maint). + (merge 9542d56379 sd/prompt-local-variable later to maint). + (merge 06d43fad18 rs/pack-write-hashwrite-simplify later to maint). + (merge b7e20b4373 mc/typofix later to maint). + (merge f6bcd9a8a4 js/test-whitespace-fixes later to maint). + (merge 53b67a801b js/test-file-size later to maint). diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 88750af7ae..dc3bceb6d1 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -11,11 +11,12 @@ -L <start>,<end>:: -L :<funcname>:: - Annotate only the given line range. May be specified multiple times. - Overlapping ranges are allowed. + Annotate only the line range given by '<start>,<end>', + or by the function name regex '<funcname>'. + May be specified multiple times. Overlapping ranges are allowed. + -<start> and <end> are optional. ``-L <start>'' or ``-L <start>,'' spans from -<start> to end of file. ``-L ,<end>'' spans from start of file to <end>. +'<start>' and '<end>' are optional. `-L <start>` or `-L <start>,` spans from +'<start>' to end of file. `-L ,<end>` spans from start of file to '<end>'. + include::line-range-format.txt[] diff --git a/Documentation/config.txt b/Documentation/config.txt index 025ca4df11..f292c2689e 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -265,7 +265,7 @@ color:: The basic colors accepted are `normal`, `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and `white`. The first color given is the foreground; the second is the background. All the basic colors except -`normal` have a bright variant that can be speficied by prefixing the +`normal` have a bright variant that can be specified by prefixing the color with `bright`, like `brightred`. + Colors may also be given as numbers between 0 and 255; these use ANSI diff --git a/Documentation/config/format.txt b/Documentation/config/format.txt index 851bf410a3..fdbc06a4d2 100644 --- a/Documentation/config/format.txt +++ b/Documentation/config/format.txt @@ -94,6 +94,11 @@ format.outputDirectory:: Set a custom directory to store the resulting files instead of the current working directory. All directory components will be created. +format.filenameMaxLength:: + The maximum length of the output filenames generated by the + `format-patch` command; defaults to 64. Can be overridden + by the `--filename-max-length=<n>` command line option. + format.useAutoBase:: A boolean value which lets you enable the `--base=auto` option of format-patch by default. Can also be set to "whenAble" to allow diff --git a/Documentation/config/maintenance.txt b/Documentation/config/maintenance.txt index a0706d8f09..a5ead09e4b 100644 --- a/Documentation/config/maintenance.txt +++ b/Documentation/config/maintenance.txt @@ -1,3 +1,23 @@ +maintenance.auto:: + This boolean config option controls whether some commands run + `git maintenance run --auto` after doing their normal work. Defaults + to true. + +maintenance.strategy:: + This string config option provides a way to specify one of a few + recommended schedules for background maintenance. This only affects + which tasks are run during `git maintenance run --schedule=X` + commands, provided no `--task=<task>` arguments are provided. + Further, if a `maintenance.<task>.schedule` config value is set, + then that value is used instead of the one provided by + `maintenance.strategy`. The possible strategy strings are: ++ +* `none`: This default setting implies no task are run at any schedule. +* `incremental`: This setting optimizes for performing small maintenance + activities that do not delete any data. This does not schedule the `gc` + task, but runs the `prefetch` and `commit-graph` tasks hourly and the + `loose-objects` and `incremental-repack` tasks daily. + maintenance.<task>.enabled:: This boolean config option controls whether the maintenance task with name `<task>` is run when no `--task` option is specified to @@ -5,6 +25,11 @@ maintenance.<task>.enabled:: `--task` option exists. By default, only `maintenance.gc.enabled` is true. +maintenance.<task>.schedule:: + This config option controls whether or not the given `<task>` runs + during a `git maintenance run --schedule=<frequency>` command. The + value must be one of "hourly", "daily", or "weekly". + maintenance.commit-graph.auto:: This integer config option controls how often the `commit-graph` task should be run as part of `git maintenance run --auto`. If zero, then diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index ee52b65e46..746b144c76 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -36,9 +36,9 @@ endif::git-format-patch[] -U<n>:: --unified=<n>:: Generate diffs with <n> lines of context instead of - the usual three. Implies `--patch`. + the usual three. ifndef::git-format-patch[] - Implies `-p`. + Implies `--patch`. endif::git-format-patch[] --output=<file>:: @@ -441,12 +441,16 @@ endif::git-format-patch[] --binary:: In addition to `--full-index`, output a binary diff that - can be applied with `git-apply`. Implies `--patch`. + can be applied with `git-apply`. +ifndef::git-format-patch[] + Implies `--patch`. +endif::git-format-patch[] --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object name in diff-raw format output and diff-tree header - lines, show only a partial prefix. + lines, show the shortest prefix that is at least '<n>' + hexdigits long that uniquely refers the object. In diff-patch output format, `--full-index` takes higher precedence, i.e. if `--full-index` is specified, full blob names will be shown regardless of `--abbrev`. @@ -700,7 +704,10 @@ endif::git-format-patch[] -W:: --function-context:: - Show whole surrounding functions of changes. + Show whole function as context lines for each change. + The function names are determined in the same way as + `git diff` works out patch hunk headers (see 'Defining a + custom hunk-header' in linkgit:gitattributes[5]). ifndef::git-format-patch[] ifndef::git-log[] diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 7e81541996..34b496d485 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -87,7 +87,9 @@ include::blame-options.txt[] --abbrev=<n>:: Instead of using the default 7+1 hexadecimal digits as the - abbreviated object name, use <n>+1 digits. Note that 1 column + abbreviated object name, use <m>+1 digits, where <m> is at + least <n> but ensures the commit object names are unique. + Note that 1 column is used for a caret to mark the boundary commit. diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index ace4ad3da8..adaa1782a8 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -9,7 +9,7 @@ SYNOPSIS -------- [verse] 'git branch' [--color[=<when>] | --no-color] [--show-current] - [-v [--abbrev=<length> | --no-abbrev]] + [-v [--abbrev=<n> | --no-abbrev]] [--column[=<options>] | --no-column] [--sort=<key>] [--merged [<commit>]] [--no-merged [<commit>]] [--contains [<commit>]] [--no-contains [<commit>]] @@ -194,8 +194,10 @@ This option is only applicable in non-verbose mode. Be more quiet when creating or deleting a branch, suppressing non-error messages. ---abbrev=<length>:: - Alter the sha1's minimum display length in the output listing. +--abbrev=<n>:: + In the verbose listing that show the commit object name, + show the shortest prefix that is at least '<n>' hexdigits + long that uniquely refers the object. The default value is 7 and can be overridden by the `core.abbrev` config option. diff --git a/Documentation/git-for-each-repo.txt b/Documentation/git-for-each-repo.txt new file mode 100644 index 0000000000..94bd19da26 --- /dev/null +++ b/Documentation/git-for-each-repo.txt @@ -0,0 +1,59 @@ +git-for-each-repo(1) +==================== + +NAME +---- +git-for-each-repo - Run a Git command on a list of repositories + + +SYNOPSIS +-------- +[verse] +'git for-each-repo' --config=<config> [--] <arguments> + + +DESCRIPTION +----------- +Run a Git command on a list of repositories. The arguments after the +known options or `--` indicator are used as the arguments for the Git +subprocess. + +THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. + +For example, we could run maintenance on each of a list of repositories +stored in a `maintenance.repo` config variable using + +------------- +git for-each-repo --config=maintenance.repo maintenance run +------------- + +This will run `git -C <repo> maintenance run` for each value `<repo>` +in the multi-valued config variable `maintenance.repo`. + + +OPTIONS +------- +--config=<config>:: + Use the given config variable as a multi-valued list storing + absolute path names. Iterate on that list of paths to run + the given arguments. ++ +These config values are loaded from system, global, and local Git config, +as available. If `git for-each-repo` is run in a directory that is not a +Git repository, then only the system and global config is used. + + +SUBPROCESS BEHAVIOR +------------------- + +If any `git -C <repo> <arguments>` subprocess returns a non-zero exit code, +then the `git for-each-repo` process returns that exit code without running +more subprocesses. + +Each `git -C <repo> <arguments>` subprocess inherits the standard file +descriptors `stdin`, `stdout`, and `stderr`. + + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index bf1bb40f63..3e49bf2210 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -28,6 +28,7 @@ SYNOPSIS [--no-notes | --notes[=<ref>]] [--interdiff=<previous>] [--range-diff=<previous> [--creation-factor=<percent>]] + [--filename-max-length=<n>] [--progress] [<common diff options>] [ <since> | <revision range> ] @@ -200,6 +201,13 @@ populated with placeholder text. allows for useful naming of a patch series, and can be combined with the `--numbered` option. +--filename-max-length=<n>:: + Instead of the standard 64 bytes, chomp the generated output + filenames at around '<n>' bytes (too short a value will be + silently raised to a reasonable length). Defaults to the + value of the `format.filenameMaxLength` configuration + variable, or 64 if unconfigured. + --rfc:: Alias for `--subject-prefix="RFC PATCH"`. RFC means "Request For Comments"; use this when sending an experimental patch for diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 6077ff01a4..4e0ba8234a 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -241,7 +241,7 @@ providing this option will cause it to die. --show-function:: Show the preceding line that contains the function name of the match, unless the matching line is a function name itself. - The name is determined in the same way as 'git diff' works out + The name is determined in the same way as `git diff` works out patch hunk headers (see 'Defining a custom hunk-header' in linkgit:gitattributes[5]). @@ -266,7 +266,9 @@ providing this option will cause it to die. Show the surrounding text from the previous line containing a function name up to the one before the next function name, effectively showing the whole function in which the match was - found. + found. The function names are determined in the same way as + `git diff` works out patch hunk headers (see 'Defining a + custom hunk-header' in linkgit:gitattributes[5]). --threads <num>:: Number of grep worker threads to use. diff --git a/Documentation/git-log.txt b/Documentation/git-log.txt index 2b8ac5ff88..dd189a353a 100644 --- a/Documentation/git-log.txt +++ b/Documentation/git-log.txt @@ -77,20 +77,7 @@ produced by `--stat`, etc. Intended to speed up tools that read log messages from `git log` output by allowing them to allocate space in advance. --L <start>,<end>:<file>:: --L :<funcname>:<file>:: - Trace the evolution of the line range given by "<start>,<end>" - (or the function name regex <funcname>) within the <file>. You may - not give any pathspec limiters. This is currently limited to - a walk starting from a single revision, i.e., you may only - give zero or one positive revision arguments, and - <start> and <end> (or <funcname>) must exist in the starting revision. - You can specify this option more than once. Implies `--patch`. - Patch output can be suppressed using `--no-patch`, but other diff formats - (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`, - `--name-only`, `--name-status`, `--check`) are not currently implemented. -+ -include::line-range-format.txt[] +include::line-range-options.txt[] <revision range>:: Show only commits in the specified revision range. When no diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt index 3cb2ebb438..cbcf5263dd 100644 --- a/Documentation/git-ls-files.txt +++ b/Documentation/git-ls-files.txt @@ -19,7 +19,7 @@ SYNOPSIS [--exclude-standard] [--error-unmatch] [--with-tree=<tree-ish>] [--full-name] [--recurse-submodules] - [--abbrev] [--] [<file>...] + [--abbrev[=<n>]] [--] [<file>...] DESCRIPTION ----------- @@ -153,7 +153,8 @@ a space) at the start of each line: --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object - lines, show only a partial prefix. + lines, show the shortest prefix that is at least '<n>' + hexdigits long that uniquely refers the object. Non default number of digits can be specified with --abbrev=<n>. --debug:: diff --git a/Documentation/git-ls-tree.txt b/Documentation/git-ls-tree.txt index a7515714da..db02d6d79a 100644 --- a/Documentation/git-ls-tree.txt +++ b/Documentation/git-ls-tree.txt @@ -62,7 +62,8 @@ OPTIONS --abbrev[=<n>]:: Instead of showing the full 40-byte hexadecimal object - lines, show only a partial prefix. + lines, show the shortest prefix that is at least '<n>' + hexdigits long that uniquely refers the object. Non default number of digits can be specified with --abbrev=<n>. --full-name:: diff --git a/Documentation/git-maintenance.txt b/Documentation/git-maintenance.txt index 3f5d8946b4..6fec1eb8dc 100644 --- a/Documentation/git-maintenance.txt +++ b/Documentation/git-maintenance.txt @@ -29,6 +29,32 @@ Git repository. SUBCOMMANDS ----------- +register:: + Initialize Git config values so any scheduled maintenance will + start running on this repository. This adds the repository to the + `maintenance.repo` config variable in the current user's global + config and enables some recommended configuration values for + `maintenance.<task>.schedule`. The tasks that are enabled are safe + for running in the background without disrupting foreground + processes. ++ +The `register` subcomand will also set the `maintenance.strategy` config +value to `incremental`, if this value is not previously set. The +`incremental` strategy uses the following schedule for each maintenance +task: ++ +-- +* `gc`: disabled. +* `commit-graph`: hourly. +* `prefetch`: hourly. +* `loose-objects`: daily. +* `incremental-repack`: daily. +-- ++ +`git maintenance register` will also disable foreground maintenance by +setting `maintenance.auto = false` in the current repository. This config +setting will remain after a `git maintenance unregister` command. + run:: Run one or more maintenance tasks. If one or more `--task` options are specified, then those tasks are run in that order. Otherwise, @@ -36,6 +62,22 @@ run:: config options are true. By default, only `maintenance.gc.enabled` is true. +start:: + Start running maintenance on the current repository. This performs + the same config updates as the `register` subcommand, then updates + the background scheduler to run `git maintenance run --scheduled` + on an hourly basis. + +stop:: + Halt the background maintenance schedule. The current repository + is not removed from the list of maintained repositories, in case + the background maintenance is restarted later. + +unregister:: + Remove the current repository from background maintenance. This + only removes the repository from the configured list. It does not + stop the background maintenance processes from running. + TASKS ----- @@ -110,7 +152,18 @@ OPTIONS only if certain thresholds are met. For example, the `gc` task runs when the number of loose objects exceeds the number stored in the `gc.auto` config setting, or when the number of pack-files - exceeds the `gc.autoPackLimit` config setting. + exceeds the `gc.autoPackLimit` config setting. Not compatible with + the `--schedule` option. + +--schedule:: + When combined with the `run` subcommand, run maintenance tasks + only if certain time conditions are met, as specified by the + `maintenance.<task>.schedule` config value for each `<task>`. + This config value specifies a number of seconds since the last + time that task ran, according to the `maintenance.<task>.lastRun` + config value. The tasks that are tested are those provided by + the `--task=<task>` option(s) or those with + `maintenance.<task>.enabled` set to true. --quiet:: Do not report progress or other information over `stderr`. @@ -122,6 +175,50 @@ OPTIONS `maintenance.<task>.enabled` configured as `true` are considered. See the 'TASKS' section for the list of accepted `<task>` values. + +TROUBLESHOOTING +--------------- +The `git maintenance` command is designed to simplify the repository +maintenance patterns while minimizing user wait time during Git commands. +A variety of configuration options are available to allow customizing this +process. The default maintenance options focus on operations that complete +quickly, even on large repositories. + +Users may find some cases where scheduled maintenance tasks do not run as +frequently as intended. Each `git maintenance run` command takes a lock on +the repository's object database, and this prevents other concurrent +`git maintenance run` commands from running on the same repository. Without +this safeguard, competing processes could leave the repository in an +unpredictable state. + +The background maintenance schedule runs `git maintenance run` processes +on an hourly basis. Each run executes the "hourly" tasks. At midnight, +that process also executes the "daily" tasks. At midnight on the first day +of the week, that process also executes the "weekly" tasks. A single +process iterates over each registered repository, performing the scheduled +tasks for that frequency. Depending on the number of registered +repositories and their sizes, this process may take longer than an hour. +In this case, multiple `git maintenance run` commands may run on the same +repository at the same time, colliding on the object database lock. This +results in one of the two tasks not running. + +If you find that some maintenance windows are taking longer than one hour +to complete, then consider reducing the complexity of your maintenance +tasks. For example, the `gc` task is much slower than the +`incremental-repack` task. However, this comes at a cost of a slightly +larger object database. Consider moving more expensive tasks to be run +less frequently. + +Expert users may consider scheduling their own maintenance tasks using a +different schedule than is available through `git maintenance start` and +Git configuration options. These users should be aware of the object +database lock and how concurrent `git maintenance run` commands behave. +Further, the `git gc` command should not be combined with +`git maintenance run` commands. `git gc` modifies the object database +but does not take the lock in the same way as `git maintenance run`. If +possible, use `git maintenance run --task=gc` instead of `git gc`. + + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-p4.txt b/Documentation/git-p4.txt index dab9609013..ec233ac0c1 100644 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@ -417,7 +417,7 @@ p4-post-changelist ~~~~~~~~~~~~~~~~~~ The `p4-post-changelist` hook is invoked after the submit has -successfully occured in P4. It takes no parameters and is meant +successfully occurred in P4. It takes no parameters and is meant primarily for notification and cannot affect the outcome of the git p4 submit action. diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt index 19b12b6d43..5013daa6ef 100644 --- a/Documentation/git-rev-parse.txt +++ b/Documentation/git-rev-parse.txt @@ -109,6 +109,10 @@ names an existing object that is a commit-ish (i.e. a commit, or an annotated tag that points at a commit). To make sure that `$VAR` names an existing object of any type, `git rev-parse "$VAR^{object}"` can be used. ++ +Note that if you are verifying a name from an untrusted source, it is +wise to use `--end-of-options` so that the name argument is not mistaken +for another option. -q:: --quiet:: @@ -446,7 +450,7 @@ $ git rev-parse --verify HEAD * Print the commit object name from the revision in the $REV shell variable: + ------------ -$ git rev-parse --verify $REV^{commit} +$ git rev-parse --verify --end-of-options $REV^{commit} ------------ + This will error out if $REV is empty or not a valid revision. @@ -454,7 +458,7 @@ This will error out if $REV is empty or not a valid revision. * Similar to above: + ------------ -$ git rev-parse --default master --verify $REV +$ git rev-parse --default master --verify --end-of-options $REV ------------ + but if $REV is empty, the commit object name from master will be printed. diff --git a/Documentation/githooks.txt b/Documentation/githooks.txt index 4e097dc4e9..ffccfc7760 100644 --- a/Documentation/githooks.txt +++ b/Documentation/githooks.txt @@ -655,7 +655,7 @@ p4-post-changelist This hook is invoked by `git-p4 submit`. The `p4-post-changelist` hook is invoked after the submit has -successfully occured in P4. It takes no parameters and is meant +successfully occurred in P4. It takes no parameters and is meant primarily for notification and cannot affect the outcome of the git p4 submit action. diff --git a/Documentation/gitk.txt b/Documentation/gitk.txt index c653ebb6a8..d50e9ed10e 100644 --- a/Documentation/gitk.txt +++ b/Documentation/gitk.txt @@ -98,25 +98,7 @@ linkgit:git-rev-list[1] for a complete list. (See "History simplification" in linkgit:git-log[1] for a more detailed explanation.) --L<start>,<end>:<file>:: --L:<funcname>:<file>:: - - Trace the evolution of the line range given by "<start>,<end>" - (or the function name regex <funcname>) within the <file>. You may - not give any pathspec limiters. This is currently limited to - a walk starting from a single revision, i.e., you may only - give zero or one positive revision arguments, and - <start> and <end> (or <funcname>) must exist in the starting revision. - You can specify this option more than once. Implies `--patch`. - Patch output can be suppressed using `--no-patch`, but other diff formats - (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`, - `--name-only`, `--name-status`, `--check`) are not currently implemented. -+ -*Note:* gitk (unlike linkgit:git-log[1]) currently only understands -this option if you specify it "glued together" with its argument. Do -*not* put a space after `-L`. -+ -include::line-range-format.txt[] +include::line-range-options.txt[] <revision range>:: diff --git a/Documentation/line-range-format.txt b/Documentation/line-range-format.txt index 829676ff98..9b51e9fb66 100644 --- a/Documentation/line-range-format.txt +++ b/Documentation/line-range-format.txt @@ -1,30 +1,32 @@ -<start> and <end> can take one of these forms: +'<start>' and '<end>' can take one of these forms: - number + -If <start> or <end> is a number, it specifies an +If '<start>' or '<end>' is a number, it specifies an absolute line number (lines count from 1). + -- /regex/ +- `/regex/` + This form will use the first line matching the given -POSIX regex. If <start> is a regex, it will search from the end of +POSIX regex. If '<start>' is a regex, it will search from the end of the previous `-L` range, if any, otherwise from the start of file. -If <start> is ``^/regex/'', it will search from the start of file. -If <end> is a regex, it will search -starting at the line given by <start>. +If '<start>' is `^/regex/`, it will search from the start of file. +If '<end>' is a regex, it will search +starting at the line given by '<start>'. + - +offset or -offset + -This is only valid for <end> and will specify a number -of lines before or after the line given by <start>. +This is only valid for '<end>' and will specify a number +of lines before or after the line given by '<start>'. + -If ``:<funcname>'' is given in place of <start> and <end>, it is a +If `:<funcname>` is given in place of '<start>' and '<end>', it is a regular expression that denotes the range from the first funcname line -that matches <funcname>, up to the next funcname line. ``:<funcname>'' +that matches '<funcname>', up to the next funcname line. `:<funcname>` searches from the end of the previous `-L` range, if any, otherwise -from the start of file. ``^:<funcname>'' searches from the start of -file. +from the start of file. `^:<funcname>` searches from the start of +file. The function names are determined in the same way as `git diff` +works out patch hunk headers (see 'Defining a custom hunk-header' +in linkgit:gitattributes[5]). diff --git a/Documentation/line-range-options.txt b/Documentation/line-range-options.txt new file mode 100644 index 0000000000..8e295a62b8 --- /dev/null +++ b/Documentation/line-range-options.txt @@ -0,0 +1,15 @@ +-L<start>,<end>:<file>:: +-L:<funcname>:<file>:: + + Trace the evolution of the line range given by '<start>,<end>', + or by the function name regex '<funcname>', within the '<file>'. You may + not give any pathspec limiters. This is currently limited to + a walk starting from a single revision, i.e., you may only + give zero or one positive revision arguments, and + '<start>' and '<end>' (or '<funcname>') must exist in the starting revision. + You can specify this option more than once. Implies `--patch`. + Patch output can be suppressed using `--no-patch`, but other diff formats + (namely `--raw`, `--numstat`, `--shortstat`, `--dirstat`, `--summary`, + `--name-only`, `--name-status`, `--check`) are not currently implemented. ++ +include::line-range-format.txt[] diff --git a/Documentation/pretty-options.txt b/Documentation/pretty-options.txt index 17c5aac4b7..27ddaf84a1 100644 --- a/Documentation/pretty-options.txt +++ b/Documentation/pretty-options.txt @@ -16,9 +16,9 @@ configuration (see linkgit:git-config[1]). --abbrev-commit:: Instead of showing the full 40-byte hexadecimal commit object - name, show only a partial prefix. Non default number of - digits can be specified with "--abbrev=<n>" (which also modifies - diff output, if it is displayed). + name, show a prefix that names the object uniquely. + "--abbrev=<n>" (which also modifies diff output, if it is displayed) + option can be used to specify the minimum length of the prefix. + This should make "--pretty=oneline" a whole lot more readable for people using 80-column terminals. |