From: Junio C Hamano Date: Thu, 28 Jul 2016 18:25:54 +0000 (-0700) Subject: Merge branch 'mm/doc-tt' into maint X-Git-Tag: v2.9.3~56 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/1032eb9c2aa34b4a908fb9d2d1cfe9680e0c34ce?ds=inline;hp=-c Merge branch 'mm/doc-tt' into maint More mark-up updates to typeset strings that are expected to literally typed by the end user in fixed-width font. * mm/doc-tt: doc: typeset HEAD and variants as literal CodingGuidelines: formatting HEAD in documentation doc: typeset long options with argument as literal doc: typeset '--' as literal doc: typeset long command-line options as literal doc: typeset short command-line options as literal Documentation/git-mv.txt: fix whitespace indentation --- 1032eb9c2aa34b4a908fb9d2d1cfe9680e0c34ce diff --combined Documentation/config.txt index 4f41840fdc,982b62009c..6ad3eb66df --- a/Documentation/config.txt +++ b/Documentation/config.txt @@@ -140,7 -140,7 +140,7 @@@ boolean: false;; Boolean false can be spelled as `no`, `off`, `false`, or `0`. + - When converting value to the canonical form using '--bool' type + When converting value to the canonical form using `--bool` type specifier; 'git config' will ensure that the output is "true" or "false" (spelled in lowercase). @@@ -481,7 -481,7 +481,7 @@@ core.worktree: If `GIT_COMMON_DIR` environment variable is set, core.worktree is ignored and not used for determining the root of 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. @@@ -633,23 -633,6 +633,23 @@@ core.attributesFile: `$XDG_CONFIG_HOME/git/attributes`. If `$XDG_CONFIG_HOME` is either not set or empty, `$HOME/.config/git/attributes` is used instead. +core.hooksPath:: + By default Git will look for your hooks in the + '$GIT_DIR/hooks' directory. Set this to different path, + e.g. '/etc/git/hooks', and Git will try to find your hooks in + that directory, e.g. '/etc/git/hooks/pre-receive' instead of + in '$GIT_DIR/hooks/pre-receive'. ++ +The path can be either absolute or relative. A relative path is +taken as relative to the directory where the hooks are run (see +the "DESCRIPTION" section of linkgit:githooks[5]). ++ +This configuration variable is useful in cases where you'd like to +centrally configure your Git hooks instead of configuring them on a +per-repository basis, or as a more flexible and centralized +alternative to having an `init.templateDir` where you've changed +default hooks. + core.editor:: Commands such as `commit` and `tag` that lets you edit messages by launching an editor uses the value of this @@@ -779,7 -762,7 +779,7 @@@ core.abbrev: add.ignoreErrors:: add.ignore-errors (deprecated):: Tells 'git add' to continue adding files when some files cannot be - added due to indexing errors. Equivalent to the '--ignore-errors' + added due to indexing errors. Equivalent to the `--ignore-errors` option of linkgit:git-add[1]. `add.ignore-errors` is deprecated, as it does not follow the usual naming convention for configuration variables. @@@ -805,9 -788,9 +805,9 @@@ from the original current directory. Se am.keepcr:: If true, git-am will call git-mailsplit for patches in mbox format - with parameter '--keep-cr'. In this case git-mailsplit will + with parameter `--keep-cr`. In this case git-mailsplit will not remove `\r` from lines ending with `\r\n`. Can be overridden - by giving '--no-keep-cr' from the command line. + by giving `--no-keep-cr` from the command line. See linkgit:git-am[1], linkgit:git-mailsplit[1]. am.threeWay:: @@@ -820,7 -803,7 +820,7 @@@ apply.ignoreWhitespace:: When set to 'change', tells 'git apply' to ignore changes in - whitespace, in the same way as the '--ignore-space-change' + whitespace, in the same way as the `--ignore-space-change` option. When set to one of: no, none, never, false tells 'git apply' to respect all whitespace differences. @@@ -828,7 -811,7 +828,7 @@@ apply.whitespace:: Tells 'git apply' how to handle whitespaces, in the same way - as the '--whitespace' option. See linkgit:git-apply[1]. + as the `--whitespace` option. See linkgit:git-apply[1]. branch.autoSetupMerge:: Tells 'git branch' and 'git checkout' to set up new branches @@@ -930,7 -913,7 +930,7 @@@ browser..cmd: browser..path:: Override the path for the given tool that may be used to - browse HTML help (see '-w' option in linkgit:git-help[1]) or a + browse HTML help (see `-w` option in linkgit:git-help[1]) or a working repository in gitweb (see linkgit:git-instaweb[1]). clean.requireForce:: @@@ -1141,16 -1124,11 +1141,16 @@@ commit.template: Specify the pathname of a file to use as the template for new commit messages. +commit.verbose:: + A boolean or int to specify the level of verbose with `git commit`. + See linkgit:git-commit[1]. + credential.helper:: Specify an external helper to be called when a username or password credential is needed; the helper may consult external - storage to avoid prompting the user for the credentials. See - linkgit:gitcredentials[7] for details. + storage to avoid prompting the user for the credentials. Note + that multiple helpers may be defined. See linkgit:gitcredentials[7] + for details. credential.useHttpPath:: When acquiring credentials, consider the "path" component of an http @@@ -1294,10 -1272,6 +1294,10 @@@ format.outputDirectory: Set a custom directory to store the resulting files instead of the current working directory. +format.useAutoBase:: + A boolean value which lets you enable the `--base=auto` option of + format-patch by default. + filter..clean:: The command which is used to convert the content of a worktree file to a blob upon checkin. See linkgit:gitattributes[5] for @@@ -1420,9 -1394,9 +1420,9 @@@ gitcvs.logFile: gitcvs.usecrlfattr:: If true, the server will look up the end-of-line conversion - attributes for files to determine the '-k' modes to use. If + attributes for files to determine the `-k` modes to use. If the attributes force Git to treat a file as text, - the '-k' mode will be left blank so CVS clients will + the `-k` mode will be left blank so CVS clients will treat it as text. If they suppress text conversion, the file will be set with '-kb' mode, which suppresses any newline munging the client might otherwise do. If the attributes do not allow @@@ -1492,16 -1466,16 +1492,16 @@@ gitweb.snapshot: See linkgit:gitweb.conf[5] for description. grep.lineNumber:: - If set to true, enable '-n' option by default. + If set to true, enable `-n` option by default. grep.patternType:: Set the default matching behavior. Using a value of 'basic', 'extended', - 'fixed', or 'perl' will enable the '--basic-regexp', '--extended-regexp', - '--fixed-strings', or '--perl-regexp' option accordingly, while the + 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`, + `--fixed-strings`, or `--perl-regexp` option accordingly, while the value 'default' will return to the default matching behavior. grep.extendedRegexp:: - If set to true, enable '--extended-regexp' option by default. This + If set to true, enable `--extended-regexp` option by default. This option is ignored when the `grep.patternType` option is set to a value other than 'default'. @@@ -1694,12 -1668,6 +1694,12 @@@ http.emptyAuth: a username in the URL, as libcurl normally requires a username for authentication. +http.extraHeader:: + Pass an additional HTTP header when communicating with a server. If + more than one such entry exists, all of them are added as extra + headers. To allow overriding the settings inherited from the system + config, an empty value will reset the extra headers to the empty list. + http.cookieFile:: The pathname of a file containing previously stored cookie lines, which should be used @@@ -1933,14 -1901,6 +1933,14 @@@ interactive.singleKey: setting is silently ignored if portable keystroke input is not available; requires the Perl module Term::ReadKey. +interactive.diffFilter:: + When an interactive command (such as `git add --patch`) shows + a colorized diff, git will pipe the diff through the shell + command defined by this configuration variable. The command may + mark up the diff further for human consumption, provided that it + retains a one-to-one correspondence with the lines in the + original diff. Defaults to disabled (no filtering). + log.abbrevCommit:: If true, makes linkgit:git-log[1], linkgit:git-show[1], and linkgit:git-whatchanged[1] assume `--abbrev-commit`. You may @@@ -1956,10 -1916,7 +1956,10 @@@ log.decorate: command. If 'short' is specified, the ref name prefixes 'refs/heads/', 'refs/tags/' and 'refs/remotes/' will not be printed. If 'full' is specified, the full ref name (including prefix) will be printed. - This is the same as the log commands `--decorate` option. + If 'auto' is specified, then if the output is going to a terminal, + the ref names are shown as if 'short' were given, otherwise no ref - names are shown. This is the same as the '--decorate' option ++ names are shown. This is the same as the `--decorate` option + of the `git log`. log.follow:: If `true`, `git log` will act as if the `--follow` option was used when @@@ -2341,16 -2298,16 +2341,16 @@@ new default) -- push.followTags:: - If set to true enable '--follow-tags' option by default. You + If set to true enable `--follow-tags` option by default. You may override this configuration at time of push by specifying - '--no-follow-tags'. + `--no-follow-tags`. push.gpgSign:: May be set to a boolean value, or the string 'if-asked'. A true - value causes all pushes to be GPG signed, as if '--signed' is + value causes all pushes to be GPG signed, as if `--signed` is passed to linkgit:git-push[1]. The string 'if-asked' causes pushes to be signed if the server supports it, as if - '--signed=if-asked' is passed to 'git push'. A false value may + `--signed=if-asked` is passed to 'git push'. A false value may override a value from a lower-priority config file. An explicit command-line flag always overrides this config option. @@@ -2373,7 -2330,7 +2373,7 @@@ rebase.stat: rebase. False by default. rebase.autoSquash:: - If set to true enable '--autosquash' option by default. + If set to true enable `--autosquash` option by default. rebase.autoStash:: When set to true, automatically create a temporary stash @@@ -2791,17 -2748,6 +2791,17 @@@ submodule..ignore: "--ignore-submodules" option. The 'git submodule' commands are not affected by this setting. +submodule.fetchJobs:: + Specifies how many submodules are fetched/cloned at the same time. + A positive integer allows up to that number of submodules fetched + in parallel. A value of 0 will give some reasonable default. + If unset, it defaults to 1. + +tag.forceSignAnnotated:: + A boolean to specify whether annotated tags created should be GPG signed. + If `--annotate` is specified on the command line, it takes + precedence over this option. + tag.sort:: This variable controls the sort ordering of tags when displayed by linkgit:git-tag[1]. Without the "--sort=" option provided, the diff --combined Documentation/diff-config.txt index f1101c7b21,0ddb7a6b4c..d5a5b17d50 --- a/Documentation/diff-config.txt +++ b/Documentation/diff-config.txt @@@ -105,16 -105,12 +105,16 @@@ diff.orderFile: diff.renameLimit:: The number of files to consider when performing the copy/rename - detection; equivalent to the 'git diff' option '-l'. + detection; equivalent to the 'git diff' option `-l`. diff.renames:: - Tells Git to detect renames. If set to any boolean value, it - will enable basic rename detection. If set to "copies" or - "copy", it will detect copies, as well. + Whether and how Git detects renames. If set to "false", + rename detection is disabled. If set to "true", basic rename + detection is enabled. If set to "copies" or "copy", Git will + detect copies, as well. Defaults to true. Note that this + affects only 'git diff' Porcelain like linkgit:git-diff[1] and + linkgit:git-log[1], and not lower level commands such as + linkgit:git-diff-files[1]. diff.suppressBlankEmpty:: A boolean to inhibit the standard behavior of printing a space @@@ -170,11 -166,6 +170,11 @@@ diff.tool: include::mergetools-diff.txt[] +diff.compactionHeuristic:: + Set this option to `true` to enable an experimental heuristic that + shifts the hunk boundary in an attempt to make the resulting + patch easier to read. + diff.algorithm:: Choose a diff algorithm. The variants are as follows: + diff --combined Documentation/fetch-options.txt index b05a8341e8,dcc68b9429..9eab1f5fa4 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@@ -52,7 -52,7 +52,7 @@@ ifndef::git-pull[ -p:: --prune:: - After fetching, remove any remote-tracking references that no + Before fetching, remove any remote-tracking references that no longer exist on the remote. Tags are not subject to pruning if they are fetched only because of the default tag auto-following or due to a --tags option. However, if tags @@@ -88,7 -88,7 +88,7 @@@ ifndef::git-pull[ to whatever else would otherwise be fetched. Using this option alone does not subject tags to pruning, even if --prune is used (though tags may be pruned anyway if they are also the - destination of an explicit refspec; see '--prune'). + destination of an explicit refspec; see `--prune`). --recurse-submodules[=yes|on-demand|no]:: This option controls if and under what conditions new commits of @@@ -110,7 -110,7 +110,7 @@@ --no-recurse-submodules:: Disable recursive fetching of submodules (this has the same effect as - using the '--recurse-submodules=no' option). + using the `--recurse-submodules=no` option). --submodule-prefix=:: Prepend to paths printed in informative messages @@@ -137,7 -137,7 +137,7 @@@ endif::git-pull[ --upload-pack :: When given, and the repository to fetch from is handled - by 'git fetch-pack', '--exec=' is passed to + by 'git fetch-pack', `--exec=` is passed to the command to specify non-default path for the command run on the other end. diff --combined Documentation/git-cherry-pick.txt index c104a594af,c95b715c8c..d35d771fc8 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@@ -47,7 -47,7 +47,7 @@@ OPTION For a more complete list of ways to spell commits, see linkgit:gitrevisions[7]. Sets of commits can be passed but no traversal is done by - default, as if the '--no-walk' option was specified, see + default, as if the `--no-walk` option was specified, see linkgit:git-rev-list[1]. Note that specifying a range will feed all ... arguments to a single revision walk (see a later example that uses 'maint master..next'). @@@ -128,7 -128,7 +128,7 @@@ effect to your index in a row --allow-empty-message:: By default, cherry-picking a commit with an empty message will fail. - This option overrides that behaviour, allowing commits with empty + This option overrides that behavior, allowing commits with empty messages to be cherry picked. --keep-redundant-commits:: diff --combined Documentation/git-commit-tree.txt index cb69faab68,ff130250be..002dae625e --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@@ -44,7 -44,7 +44,7 @@@ OPTION An existing tree object -p :: - Each '-p' indicates the id of a parent commit object. + Each `-p` indicates the id of a parent commit object. -m :: A paragraph in the commit log message. This can be given more than @@@ -61,8 -61,8 +61,8 @@@ stuck to the option without a space. --no-gpg-sign:: - Countermand `commit.gpgSign` configuration variable that is - set to force each and every commit to be signed. + Do not GPG-sign commit, to countermand a `--gpg-sign` option + given earlier on the command line. Commit Information diff --combined Documentation/git-commit.txt index e7049537d9,448f42c839..b0a294d3b5 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@@ -75,7 -75,7 +75,7 @@@ OPTION -c :: --reedit-message=:: - Like '-C', but with '-c' the editor is invoked, so that + Like '-C', but with `-c` the editor is invoked, so that the user can further edit the commit message. --fixup=:: @@@ -260,7 -260,7 +260,7 @@@ FROM UPSTREAM REBASE" section in linkgi staged for other paths. This is the default mode of operation of 'git commit' if any paths are given on the command line, in which case this option can be omitted. - If this option is specified together with '--amend', then + If this option is specified together with `--amend`, then no paths need to be specified, which can be used to amend the last commit without committing changes that have already been staged. @@@ -290,8 -290,7 +290,8 @@@ configuration variable documented in li what changes the commit has. Note that this diff output doesn't have its lines prefixed with '#'. This diff will not be a part - of the commit message. + of the commit message. See the `commit.verbose` configuration + variable in linkgit:git-config[1]. + If specified twice, show in addition the unified diff between what would be committed and the worktree files, i.e. the unstaged diff --combined Documentation/git-p4.txt index 9d4f1519e7,ac7e6a38c0..c83aaf39c3 --- a/Documentation/git-p4.txt +++ b/Documentation/git-p4.txt @@@ -104,7 -104,7 +104,7 @@@ $ git p4 sync //path/in/your/perforce/d ------------ This imports the specified depot into 'refs/remotes/p4/master' in an existing Git repository. The - '--branch' option can be used to specify a different branch to + `--branch` option can be used to specify a different branch to be used for the p4 content. If a Git repository includes branches 'refs/remotes/origin/p4', these @@@ -114,7 -114,7 +114,7 @@@ from a Git remote, this can be useful i If there are multiple branches, doing 'git p4 sync' will automatically use the "BRANCH DETECTION" algorithm to try to partition new changes - into the right branch. This can be overridden with the '--branch' + into the right branch. This can be overridden with the `--branch` option to specify just a single branch to update. @@@ -150,10 -150,10 +150,10 @@@ $ git p4 submit topicbranc ------------ The upstream reference is generally 'refs/remotes/p4/master', but can - be overridden using the '--origin=' command-line option. + be overridden using the `--origin=` command-line option. The p4 changes will be created as the user invoking 'git p4 submit'. The - '--preserve-user' option will cause ownership to be modified + `--preserve-user` option will cause ownership to be modified according to the author of the Git commit. This option requires admin privileges in p4, which can be granted using 'p4 protect'. @@@ -221,7 -221,7 +221,7 @@@ Git repository where they will be treated as remote-tracking branches by linkgit:git-branch[1] and other commands. This option instead puts p4 branches in 'refs/heads/p4/'. Note that future - sync operations must specify '--import-local' as well so that + sync operations must specify `--import-local` as well so that they can find the p4 branches in refs/heads. --max-changes :: @@@ -245,7 -245,7 +245,7 @@@ default, involves removing the entire depot path. With this option, the full p4 depot path is retained in Git. For example, path '//depot/main/foo/bar.c', when imported from - '//depot/main/', becomes 'foo/bar.c'. With '--keep-path', the + '//depot/main/', becomes 'foo/bar.c'. With `--keep-path`, the Git path is instead 'depot/main/foo/bar.c'. --use-client-spec:: @@@ -275,7 -275,7 +275,7 @@@ These options can be used to modify 'gi --origin :: Upstream location from which commits are identified to submit to p4. By default, this is the most recent p4 commit reachable - from 'HEAD'. + from `HEAD`. -M:: Detect renames. See linkgit:git-diff[1]. Renames will be @@@ -341,7 -341,7 +341,7 @@@ p4 revision specifier on the end Import all changes from both named depot paths into a single repository. Only files below these directories are included. There is not a subdirectory in Git for each "proj1" and "proj2". - You must use the '--destination' option when specifying more + You must use the `--destination` option when specifying more than one depot path. The revision specifier must be specified identically on each depot path. If there are files in the depot paths with the same name, the path with the most recently @@@ -355,7 -355,7 +355,7 @@@ CLIENT SPE 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. The 'clone' and 'sync' commands - can consult the client spec when given the '--use-client-spec' option or + 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 @@@ -390,7 -390,7 +390,7 @@@ different areas in the tree, and indica can use these mappings to determine branch relationships. If you have a repository where all the branches of interest exist as - subdirectories of a single depot path, you can use '--detect-branches' + subdirectories of a single depot path, you can use `--detect-branches` when cloning or syncing to have 'git p4' automatically find subdirectories in p4, and to generate these as branches in Git. @@@ -507,7 -507,7 +507,7 @@@ git-p4.labelImportRegexp: git-p4.useClientSpec:: Specify that the p4 client spec should be used to identify p4 depot paths of interest. This is equivalent to specifying the - option '--use-client-spec'. See the "CLIENT SPEC" section above. + option `--use-client-spec`. See the "CLIENT SPEC" section above. This variable is a boolean, not the name of a p4 client. git-p4.pathEncoding:: @@@ -551,17 -551,6 +551,17 @@@ git-p4.keepEmptyCommits: A changelist that contains only excluded files will be imported as an empty commit if this boolean option is set to true. +git-p4.mapUser:: + Map a P4 user to a name and email address in Git. Use a string + with the following format to create a mapping: ++ +------------- +git config --add git-p4.mapUser "p4user = First Last " +------------- ++ +A mapping will override any user information from P4. Mappings for +multiple P4 user can be defined. + Submit variables ~~~~~~~~~~~~~~~~ git-p4.detectRenames:: diff --combined Documentation/git-rebase.txt index 0387b40e0a,a8078ff2a9..de222c81af --- a/Documentation/git-rebase.txt +++ b/Documentation/git-rebase.txt @@@ -208,10 -208,10 +208,10 @@@ rebase.stat: rebase. False by default. rebase.autoSquash:: - If set to true enable '--autosquash' option by default. + If set to true enable `--autosquash` option by default. rebase.autoStash:: - If set to true enable '--autostash' option by default. + If set to true enable `--autostash` option by default. rebase.missingCommitsCheck:: If set to "warn", print warnings about removed commits in @@@ -220,7 -220,7 +220,7 @@@ done. "ignore" by default. rebase.instructionFormat:: - Custom commit list format to use during an '--interactive' rebase. + Custom commit list format to use during an `--interactive` rebase. OPTIONS ------- @@@ -391,6 -391,9 +391,6 @@@ idea unless you know what you are doin final history. will be interpreted as one or more shell commands. + -This option can only be used with the `--interactive` option -(see INTERACTIVE MODE below). -+ You may execute several commands by either using one instance of `--exec` with several commands: + @@@ -403,9 -406,6 +403,9 @@@ or by giving more than one `--exec` If `--autosquash` is used, "exec" lines will not be appended for the intermediate commits, and will only appear at the end of each squash/fixup series. ++ +This uses the `--interactive` machinery internally, but it can be run +without an explicit `--interactive`. --root:: Rebase all commits reachable from , instead of @@@ -428,9 -428,9 +428,9 @@@ "fixup! " or "squash! " after the first, in case you referred to an earlier fixup/squash with `git commit --fixup/--squash`. + - This option is only valid when the '--interactive' option is used. + This option is only valid when the `--interactive` option is used. + - If the '--autosquash' option is enabled by default using the + If the `--autosquash` option is enabled by default using the configuration variable `rebase.autoSquash`, this option can be used to override and disable this setting. diff --combined Documentation/git-send-email.txt index d0b38b4b10,d85b878139..642d0ef199 --- a/Documentation/git-send-email.txt +++ b/Documentation/git-send-email.txt @@@ -66,7 -66,7 +66,7 @@@ This option may be specified multiple t Invoke a text editor (see GIT_EDITOR in linkgit:git-var[1]) to edit an introductory message for the patch series. + - When '--compose' is used, git send-email will use the From, Subject, and + 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, @@@ -182,19 -182,19 +182,19 @@@ $ git send-email --smtp-auth="PLAIN LOG + If at least one of the specified mechanisms matches the ones advertised by the SMTP server and if it is supported by the utilized SASL library, the mechanism - is used for authentication. If neither 'sendemail.smtpAuth' nor '--smtp-auth' + is used for authentication. If neither 'sendemail.smtpAuth' nor `--smtp-auth` is specified, all mechanisms supported by the SASL library can be used. --smtp-pass[=]:: Password for SMTP-AUTH. The argument is optional: If no argument is specified, then the empty string is used as the password. Default is the value of `sendemail.smtpPass`, - however '--smtp-pass' always overrides this value. + however `--smtp-pass` always overrides this value. + Furthermore, passwords need not be specified in configuration files or on the command line. If a username has been specified (with - '--smtp-user' or a `sendemail.smtpUser`), but no password has been - specified (with '--smtp-pass' or `sendemail.smtpPass`), then + `--smtp-user` or a `sendemail.smtpUser`), but no password has been + specified (with `--smtp-pass` or `sendemail.smtpPass`), then a password is obtained using 'git-credential'. --smtp-server=:: @@@ -240,7 -240,7 +240,7 @@@ must be used for each option --smtp-user=:: Username for SMTP-AUTH. Default is the value of `sendemail.smtpUser`; - if a username is not specified (with '--smtp-user' or `sendemail.smtpUser`), + if a username is not specified (with `--smtp-user` or `sendemail.smtpUser`), then authentication is not attempted. --smtp-debug=0|1:: @@@ -364,8 -364,8 +364,8 @@@ have been specified, in which case defa --[no-]format-patch:: When an argument may be understood either as a reference or as a file name, - choose to understand it as a format-patch argument ('--format-patch') - or as a file name ('--no-format-patch'). By default, when such a conflict + choose to understand it as a format-patch argument (`--format-patch`) + or as a file name (`--no-format-patch`). By default, when such a conflict occurs, git send-email will fail. --quiet:: @@@ -382,7 -382,7 +382,7 @@@ -- + Default is the value of `sendemail.validate`; if this is not set, - default to '--validate'. + default to `--validate`. --force:: Send emails even if safety checks would prevent it. @@@ -428,13 -428,13 +428,13 @@@ sendmail; sendemail.multiEdit:: If true (default), a single editor instance will be spawned to edit - files you have to edit (patches when '--annotate' is used, and the - summary when '--compose' is used). If false, files will be edited one + files you have to edit (patches when `--annotate` is used, and the + summary when `--compose` is used). If false, files will be edited one after the other, spawning a new editor each time. sendemail.confirm:: Sets the default for whether to confirm before sending. Must be - one of 'always', 'never', 'cc', 'compose', or 'auto'. See '--confirm' + one of 'always', 'never', 'cc', 'compose', or 'auto'. See `--confirm` in the previous section for the meaning of these values. EXAMPLE @@@ -450,19 -450,6 +450,19 @@@ edit ~/.gitconfig to specify your accou smtpUser = yourname@gmail.com smtpServerPort = 587 +If you have multifactor authentication setup on your gmail account, you will +need to generate an app-specific password for use with 'git send-email'. Visit +https://security.google.com/settings/security/apppasswords to setup an +app-specific password. Once setup, you can store it with the credentials +helper: + + $ git credential fill + protocol=smtp + host=smtp.gmail.com + username=youname@gmail.com + password=app-password + + Once your commits are ready to be sent to the mailing list, run the following commands: diff --combined Documentation/git-svn.txt index 698a6685f6,935d3c27f2..7e17cade7f --- a/Documentation/git-svn.txt +++ b/Documentation/git-svn.txt @@@ -98,11 -98,11 +98,11 @@@ your Perl's Getopt::Long is < v2.37) --ignore-paths=;; When passed to 'init' or 'clone' this regular expression will be preserved as a config key. See 'fetch' for a description - of '--ignore-paths'. + of `--ignore-paths`. --include-paths=;; When passed to 'init' or 'clone' this regular expression will be preserved as a config key. See 'fetch' for a description - of '--include-paths'. + of `--include-paths`. --no-minimize-url;; When tracking multiple directories (using --stdlayout, --branches, or --tags options), git svn will attempt to connect @@@ -110,7 -110,7 +110,7 @@@ repository. This default allows better tracking of history if entire projects are moved within a repository, but may cause issues on repositories where read access restrictions are in - place. Passing '--no-minimize-url' will allow git svn to + place. Passing `--no-minimize-url` will allow git svn to accept URLs as-is without attempting to connect to a higher level directory. This option is off by default when only one URL/branch is tracked (it would do little good). @@@ -141,7 -141,7 +141,7 @@@ the same local time zone --ignore-paths=;; This allows one to specify a Perl regular expression that will cause skipping of all matching paths from checkout from SVN. - The '--ignore-paths' option should match for every 'fetch' + The `--ignore-paths` option should match for every 'fetch' (including automatic fetches due to 'clone', 'dcommit', 'rebase', etc) on a given repository. + @@@ -170,10 -170,10 +170,10 @@@ Skip "branches" and "tags" of first lev --include-paths=;; This allows one to specify a Perl regular expression that will cause the inclusion of only matching paths from checkout from SVN. - The '--include-paths' option should match for every 'fetch' + The `--include-paths` option should match for every 'fetch' (including automatic fetches due to 'clone', 'dcommit', - 'rebase', etc) on a given repository. '--ignore-paths' takes - precedence over '--include-paths'. + 'rebase', etc) on a given repository. `--ignore-paths` takes + precedence over `--include-paths`. + [verse] config key: svn-remote..include-paths @@@ -191,7 -191,7 +191,7 @@@ or if a second argument is passed; it will create a directory and work within that. It accepts all arguments that the 'init' and 'fetch' commands accept; with the exception of - '--fetch-all' and '--parent'. After a repository is cloned, + `--fetch-all` and `--parent`. After a repository is cloned, the 'fetch' command will be able to update revisions without affecting the working tree; and the 'rebase' command will be able to update the working tree with the latest changes. @@@ -216,7 -216,7 +216,7 @@@ it preserves linear history with 'git r 'git merge' for ease of dcommitting with 'git svn'. + This accepts all options that 'git svn fetch' and 'git rebase' - accept. However, '--fetch-all' only fetches from the current + accept. However, `--fetch-all` only fetches from the current [svn-remote], and not all [svn-remote] definitions. + Like 'git rebase'; this requires that the working tree be clean @@@ -459,20 -459,6 +459,20 @@@ Any other arguments are passed directl Gets the Subversion property given as the first argument, for a file. A specific revision can be specified with -r/--revision. +'propset':: + Sets the Subversion property given as the first argument, to the + value given as the second argument for the file given as the + third argument. ++ +Example: ++ +------------------------------------------------------------------------ +git svn propset svn:keywords "FreeBSD=%H" devel/py-tipper/Makefile +------------------------------------------------------------------------ ++ +This will set the property 'svn:keywords' to 'FreeBSD=%H' for the file +'devel/py-tipper/Makefile'. + 'show-externals':: Shows the Subversion externals. Use -r/--revision to specify a specific revision. @@@ -919,7 -905,7 +919,7 @@@ parent of the branch. However, it is po Git commit to serve as parent. This will happen, among other reasons, if the SVN branch is a copy of a revision that was not fetched by 'git svn' (e.g. because it is an old revision that was skipped with - '--revision'), or if in SVN a directory was copied that is not tracked + `--revision`), or if in SVN a directory was copied that is not tracked by 'git svn' (such as a branch that is not tracked at all, or a subdirectory of a tracked branch). In these cases, 'git svn' will still create a Git branch, but instead of using an existing Git commit as the @@@ -996,12 -982,12 +996,12 @@@ directories in the working copy. Whil copy of a complete repository, for projects with many branches it will lead to a working copy many times larger than just the trunk. Thus for projects using the standard directory structure (trunk/branches/tags), - it is recommended to clone with option '--stdlayout'. If the project + it is recommended to clone with option `--stdlayout`. If the project uses a non-standard structure, and/or if branches and tags are not required, it is easiest to only clone one directory (typically trunk), without giving any repository layout options. If the full history with - branches and tags is required, the options '--trunk' / '--branches' / - '--tags' must be used. + branches and tags is required, the options `--trunk` / `--branches` / + `--tags` must be used. When using multiple --branches or --tags, 'git svn' does not automatically handle name collisions (for example, if two branches from different paths have diff --combined Documentation/git-tag.txt index 6b89393746,dfd6b27682..7ecca8e247 --- a/Documentation/git-tag.txt +++ b/Documentation/git-tag.txt @@@ -78,7 -78,7 +78,7 @@@ OPTION -v:: --verify:: - Verify the gpg signature of the given tag names. + Verify the GPG signature of the given tag names. -n:: specifies how many lines from the annotation, if any, @@@ -167,7 -167,7 +167,7 @@@ This option is only applicable when lis --[no-]merged []:: Only list tags whose tips are reachable, or not reachable - if '--no-merged' is used, from the specified commit ('HEAD' + if `--no-merged` is used, from the specified commit (`HEAD` if not specified). CONFIGURATION diff --combined Documentation/git.txt index 4ee0b36360,56d579b583..ff25701d4e --- a/Documentation/git.txt +++ b/Documentation/git.txt @@@ -31,8 -31,8 +31,8 @@@ page to learn what commands Git offers individual Git commands with "git help command". linkgit:gitcli[7] 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`. +A formatted and hyperlinked copy of the latest Git documentation +can be viewed at `https://git.github.io/htmldocs/git.html`. ifdef::stalenotes[] [NOTE] @@@ -43,13 -43,6 +43,13 @@@ unreleased) version of Git, that is ava branch of the `git.git` repository. Documentation for older releases are available here: +* link:v2.9.2/git.html[documentation for release 2.9.2] + +* release notes for + link:RelNotes/2.9.2.txt[2.9.2], + link:RelNotes/2.9.1.txt[2.9.1], + link:RelNotes/2.9.0.txt[2.9]. + * link:v2.8.4/git.html[documentation for release 2.8.4] * release notes for @@@ -515,7 -508,7 +515,7 @@@ OPTION --help:: Prints the synopsis and a list of the most commonly used - commands. If the option '--all' or '-a' is given then all + commands. If the option `--all` or `-a` is given then all available commands are printed. If a Git command is named this option will bring up the manual page for that command. + @@@ -857,16 -850,16 +857,16 @@@ Git so take care if using a foreign fro If the `GIT_DIR` environment variable is set then it specifies a path to use instead of the default `.git` for the base of the repository. - The '--git-dir' command-line option also sets this value. + The `--git-dir` command-line option also sets this value. `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`:: Set the Git namespace; see linkgit:gitnamespaces[7] for details. - The '--namespace' command-line option also sets this value. + The `--namespace` command-line option also sets this value. `GIT_CEILING_DIRECTORIES`:: This should be a colon-separated list of absolute paths. If @@@ -981,7 -974,7 +981,7 @@@ othe The command will be given exactly two or four arguments: the 'username@host' (or just 'host') from the URL and the shell command to execute on that remote system, optionally preceded by - '-p' (literally) and the 'port' from the URL when it specifies + `-p` (literally) and the 'port' from the URL when it specifies something other than the default SSH port. + `$GIT_SSH_COMMAND` takes precedence over `$GIT_SSH`, and is interpreted