# [RFC PATCH v1 00/13][GSoC] doc: (monospace) apply CodingGuidelines on a large-scale 20 messages from 2021-04-09 to 2021-04-19. Participants: Firmin Martin, Bagas Sanjaya, Jean-Noël Avila. Thread: https://gitlist.dev/t/55461 ## Firmin Martin, 2021-04-09 04:02 Subject: [RFC PATCH v1 00/13][GSoC] doc: (monospace) apply CodingGuidelines on a large-scale Message-ID: <20210409040301.3260358-1-firminmartin24@gmail.com> URL: https://gitlist.dev/e/20210409040301.3260358-1-firminmartin24%40gmail.com ``` This patch series aims to make the documentation fully compliant to the CodingGuidelines regarding monospace font. After it, new contributors who just want to change a little portion of the documention could just look around how it has been done without being confused by the inconsistency between the documentation and the CodingGuidelines. Concretely: unquoted, single-quoted or double-quoted entities detailed below in the summary are wrapped or converted in backticks. Except some easy cases, the methodology consists of using simple regex to find relevant files, then interactively substitute targeted entities with progressively smarter regex to exclude false positives. As the review process could be very tedious, I have been very cautious and have reviewed myself a couple of times every changes. Consequently, mistakes, if there are any, are not due to the regex, but my personal misinterpretation of the context. Below is some changes I plan to make in v2 which request comments/approvals of the community. * Placeholders and option values should be in italic. (Cf. man man) - e.g. `--date`='', `--notes`[=''], `branch.`''`.remote` - e.g. `--date`='rfc2822' - Compare gcc and git-add - man gcc vs. man git-add - https://linux.die.net/man/1/gcc vs. https://linux.die.net/man/1/git-add * The Synopsis section should be formatted based on the current CodingGuidelines plus the above suggestion. IOW, for instance, options should be wrapped in backticks. Again, to have an idea, compare gcc and git-add. Best, Firmin Firmin Martin (13): doc: typeset command-line options in monospace doc: typeset branches and remotes in monospace doc: typeset configuration options in monospace doc: typeset git-related commands in monospace doc: typeset git-svn subcommands in monospace doc: typeset dummy URLs and protocols in monospace doc: typeset git dotfiles in monospace doc: typeset filepath and $variables in monospace doc: typeset command/option/value entries in monospace doc: typeset more command entries in monospace doc: typeset config option entries in monospace doc: typeset environment vars without $ in monospace doc: typeset common programs in monospace Documentation/CodingGuidelines | 2 +- Documentation/MyFirstContribution.txt | 8 +- Documentation/SubmittingPatches | 2 +- Documentation/blame-options.txt | 50 +- Documentation/config.txt | 38 +- Documentation/config/diff.txt | 2 +- Documentation/config/gitcvs.txt | 6 +- Documentation/diff-format.txt | 12 +- Documentation/diff-generate-patch.txt | 8 +- Documentation/diff-options.txt | 252 +++---- Documentation/fetch-options.txt | 136 ++-- Documentation/git-add.txt | 86 +-- Documentation/git-am.txt | 116 +-- Documentation/git-apply.txt | 84 +-- Documentation/git-archimport.txt | 34 +- Documentation/git-archive.txt | 52 +- Documentation/git-bisect-lk2009.txt | 188 ++--- Documentation/git-bisect.txt | 48 +- Documentation/git-blame.txt | 32 +- Documentation/git-branch.txt | 156 ++-- Documentation/git-bugreport.txt | 14 +- Documentation/git-bundle.txt | 74 +- Documentation/git-cat-file.txt | 42 +- Documentation/git-check-attr.txt | 18 +- Documentation/git-check-ignore.txt | 16 +- Documentation/git-check-mailmap.txt | 4 +- Documentation/git-check-ref-format.txt | 16 +- Documentation/git-checkout-index.txt | 42 +- Documentation/git-checkout.txt | 114 +-- Documentation/git-cherry-pick.txt | 76 +- Documentation/git-cherry.txt | 20 +- Documentation/git-citool.txt | 6 +- Documentation/git-clean.txt | 66 +- Documentation/git-clone.txt | 104 +-- Documentation/git-column.txt | 26 +- Documentation/git-commit-graph.txt | 12 +- Documentation/git-commit-tree.txt | 22 +- Documentation/git-commit.txt | 174 ++--- Documentation/git-config.txt | 174 ++--- Documentation/git-count-objects.txt | 16 +- .../git-credential-cache--daemon.txt | 2 +- Documentation/git-credential-cache.txt | 8 +- Documentation/git-credential-store.txt | 12 +- Documentation/git-credential.txt | 16 +- Documentation/git-cvsexportcommit.txt | 46 +- Documentation/git-cvsimport.txt | 84 +-- Documentation/git-cvsserver.txt | 110 +-- Documentation/git-daemon.txt | 150 ++-- Documentation/git-describe.txt | 80 +- Documentation/git-diff-files.txt | 18 +- Documentation/git-diff-index.txt | 34 +- Documentation/git-diff-tree.txt | 46 +- Documentation/git-diff.txt | 64 +- Documentation/git-difftool.txt | 78 +- Documentation/git-fast-export.txt | 84 +-- Documentation/git-fast-import.txt | 140 ++-- Documentation/git-fetch-pack.txt | 72 +- Documentation/git-fetch.txt | 46 +- Documentation/git-filter-branch.txt | 164 ++--- Documentation/git-fmt-merge-msg.txt | 30 +- Documentation/git-for-each-ref.txt | 80 +- Documentation/git-for-each-repo.txt | 4 +- Documentation/git-format-patch.txt | 132 ++-- Documentation/git-fsck-objects.txt | 2 +- Documentation/git-fsck.txt | 74 +- Documentation/git-gc.txt | 36 +- Documentation/git-get-tar-commit-id.txt | 8 +- Documentation/git-grep.txt | 178 ++--- Documentation/git-gui.txt | 32 +- Documentation/git-hash-object.txt | 20 +- Documentation/git-help.txt | 78 +- Documentation/git-http-backend.txt | 72 +- Documentation/git-http-fetch.txt | 24 +- Documentation/git-http-push.txt | 22 +- Documentation/git-imap-send.txt | 20 +- Documentation/git-index-pack.txt | 48 +- Documentation/git-init-db.txt | 2 +- Documentation/git-init.txt | 28 +- Documentation/git-instaweb.txt | 44 +- Documentation/git-interpret-trailers.txt | 80 +- Documentation/git-log.txt | 56 +- Documentation/git-ls-files.txt | 126 ++-- Documentation/git-ls-remote.txt | 46 +- Documentation/git-ls-tree.txt | 38 +- Documentation/git-mailinfo.txt | 36 +- Documentation/git-mailsplit.txt | 20 +- Documentation/git-maintenance.txt | 32 +- Documentation/git-merge-base.txt | 32 +- Documentation/git-merge-file.txt | 26 +- Documentation/git-merge-index.txt | 16 +- Documentation/git-merge-one-file.txt | 6 +- Documentation/git-merge-tree.txt | 4 +- Documentation/git-merge.txt | 78 +- Documentation/git-mergetool--lib.txt | 8 +- Documentation/git-mergetool.txt | 40 +- Documentation/git-mktag.txt | 4 +- Documentation/git-mktree.txt | 8 +- Documentation/git-multi-pack-index.txt | 18 +- Documentation/git-mv.txt | 28 +- Documentation/git-name-rev.txt | 32 +- Documentation/git-notes.txt | 170 ++--- Documentation/git-p4.txt | 318 ++++---- Documentation/git-pack-objects.txt | 122 ++-- Documentation/git-pack-redundant.txt | 10 +- Documentation/git-pack-refs.txt | 12 +- Documentation/git-patch-id.txt | 22 +- Documentation/git-prune-packed.txt | 10 +- Documentation/git-prune.txt | 30 +- Documentation/git-pull.txt | 42 +- Documentation/git-push.txt | 136 ++-- Documentation/git-quiltimport.txt | 18 +- Documentation/git-range-diff.txt | 16 +- Documentation/git-read-tree.txt | 118 +-- Documentation/git-rebase.txt | 384 +++++----- Documentation/git-receive-pack.txt | 48 +- Documentation/git-reflog.txt | 36 +- Documentation/git-remote-ext.txt | 40 +- Documentation/git-remote-fd.txt | 16 +- Documentation/git-remote.txt | 62 +- Documentation/git-repack.txt | 64 +- Documentation/git-replace.txt | 42 +- Documentation/git-request-pull.txt | 12 +- Documentation/git-rerere.txt | 80 +- Documentation/git-reset.txt | 60 +- Documentation/git-restore.txt | 58 +- Documentation/git-rev-list.txt | 6 +- Documentation/git-rev-parse.txt | 148 ++-- Documentation/git-revert.txt | 54 +- Documentation/git-rm.txt | 32 +- Documentation/git-send-email.txt | 192 ++--- Documentation/git-send-pack.txt | 44 +- Documentation/git-sh-i18n--envsubst.txt | 2 +- Documentation/git-sh-i18n.txt | 4 +- Documentation/git-sh-setup.txt | 10 +- Documentation/git-shell.txt | 26 +- Documentation/git-shortlog.txt | 32 +- Documentation/git-show-branch.txt | 66 +- Documentation/git-show-index.txt | 4 +- Documentation/git-show-ref.txt | 58 +- Documentation/git-show.txt | 12 +- Documentation/git-sparse-checkout.txt | 18 +- Documentation/git-stage.txt | 2 +- Documentation/git-stash.txt | 80 +- Documentation/git-status.txt | 78 +- Documentation/git-stripspace.txt | 16 +- Documentation/git-submodule.txt | 172 ++--- Documentation/git-svn.txt | 690 +++++++++--------- Documentation/git-switch.txt | 76 +- Documentation/git-symbolic-ref.txt | 22 +- Documentation/git-tag.txt | 108 +-- Documentation/git-unpack-file.txt | 4 +- Documentation/git-unpack-objects.txt | 12 +- Documentation/git-update-index.txt | 132 ++-- Documentation/git-update-ref.txt | 40 +- Documentation/git-update-server-info.txt | 6 +- Documentation/git-upload-archive.txt | 10 +- Documentation/git-upload-pack.txt | 20 +- Documentation/git-var.txt | 20 +- Documentation/git-verify-commit.txt | 10 +- Documentation/git-verify-pack.txt | 14 +- Documentation/git-verify-tag.txt | 10 +- Documentation/git-web--browse.txt | 26 +- Documentation/git-whatchanged.txt | 8 +- Documentation/git-worktree.txt | 74 +- Documentation/git-write-tree.txt | 12 +- Documentation/git.txt | 142 ++-- Documentation/gitattributes.txt | 88 +-- Documentation/gitcli.txt | 6 +- Documentation/gitcore-tutorial.txt | 212 +++--- Documentation/gitcredentials.txt | 20 +- Documentation/gitcvs-migration.txt | 14 +- Documentation/gitdiffcore.txt | 60 +- Documentation/giteveryday.txt | 24 +- Documentation/gitfaq.txt | 6 +- Documentation/githooks.txt | 26 +- Documentation/gitignore.txt | 16 +- Documentation/gitk.txt | 64 +- Documentation/gitmailmap.txt | 2 +- Documentation/gitmodules.txt | 26 +- Documentation/gitnamespaces.txt | 12 +- Documentation/gitremote-helpers.txt | 90 +-- Documentation/gitrepository-layout.txt | 114 +-- Documentation/gitsubmodules.txt | 2 +- Documentation/gittutorial-2.txt | 38 +- Documentation/gittutorial.txt | 100 +-- Documentation/gitweb.conf.txt | 320 ++++---- Documentation/gitweb.txt | 168 ++--- Documentation/gitworkflows.txt | 76 +- Documentation/glossary-content.txt | 38 +- Documentation/howto/revert-branch-rebase.txt | 2 +- .../howto/setup-git-server-over-http.txt | 2 +- Documentation/i18n.txt | 4 +- Documentation/merge-options.txt | 100 +-- Documentation/merge-strategies.txt | 36 +- Documentation/pretty-formats.txt | 16 +- Documentation/pretty-options.txt | 52 +- Documentation/pull-fetch-param.txt | 18 +- Documentation/rev-list-options.txt | 242 +++--- Documentation/revisions.txt | 76 +- Documentation/sequencer.txt | 8 +- Documentation/signoff-option.txt | 8 +- Documentation/urls-remotes.txt | 12 +- Documentation/urls.txt | 40 +- Documentation/user-manual.txt | 116 +-- 204 files changed, 5971 insertions(+), 5971 deletions(-) -- 2.31.1.133.g84d06cdc06 ``` ## Firmin Martin, 2021-04-09 04:02 Subject: [RFC PATCH v1 01/13] doc: typeset command-line options in monospace Message-ID: <20210409040301.3260358-2-firminmartin24@gmail.com> URL: https://gitlist.dev/e/20210409040301.3260358-2-firminmartin24%40gmail.com In-Reply-To: <20210409040301.3260358-1-firminmartin24@gmail.com> ``` Wrap command-line options with backticks as indicated in the CodingGuidelines. The following command and regex assisted the process. REGEX="^(?![[:blank:]]*[\$]).*[^-\`+<[:punct:][:alnum:]]\-{1,2}[[:alpha:]][a-z0-9-]*(=[\"<]?([[:alnum:]])+[>\"]?)?[^\`-]" && grep -Pn "$REGEX" *.txt --exclude-dir=RelNotes Signed-off-by: Firmin Martin --- Documentation/SubmittingPatches | 2 +- Documentation/blame-options.txt | 6 +- Documentation/config/diff.txt | 2 +- Documentation/config/gitcvs.txt | 6 +- Documentation/diff-generate-patch.txt | 4 +- Documentation/diff-options.txt | 8 +- Documentation/fetch-options.txt | 16 +-- Documentation/git-add.txt | 2 +- Documentation/git-apply.txt | 2 +- Documentation/git-archimport.txt | 2 +- Documentation/git-archive.txt | 2 +- Documentation/git-branch.txt | 2 +- Documentation/git-bundle.txt | 10 +- Documentation/git-checkout-index.txt | 6 +- Documentation/git-checkout.txt | 4 +- Documentation/git-cherry-pick.txt | 2 +- Documentation/git-clean.txt | 8 +- Documentation/git-clone.txt | 4 +- Documentation/git-column.txt | 2 +- Documentation/git-commit.txt | 16 +-- Documentation/git-config.txt | 6 +- Documentation/git-count-objects.txt | 6 +- Documentation/git-cvsexportcommit.txt | 8 +- Documentation/git-cvsimport.txt | 12 +- Documentation/git-cvsserver.txt | 12 +- Documentation/git-daemon.txt | 22 ++-- Documentation/git-describe.txt | 18 +-- Documentation/git-diff-tree.txt | 6 +- Documentation/git-diff.txt | 6 +- Documentation/git-fast-export.txt | 10 +- Documentation/git-fast-import.txt | 42 +++---- Documentation/git-fetch-pack.txt | 4 +- Documentation/git-fetch.txt | 6 +- Documentation/git-filter-branch.txt | 26 ++--- Documentation/git-fmt-merge-msg.txt | 2 +- Documentation/git-for-each-ref.txt | 4 +- Documentation/git-format-patch.txt | 6 +- Documentation/git-fsck.txt | 6 +- Documentation/git-gc.txt | 4 +- Documentation/git-grep.txt | 4 +- Documentation/git-help.txt | 8 +- Documentation/git-http-fetch.txt | 2 +- Documentation/git-http-push.txt | 2 +- Documentation/git-index-pack.txt | 12 +- Documentation/git-init.txt | 2 +- Documentation/git-interpret-trailers.txt | 18 +-- Documentation/git-ls-files.txt | 24 ++-- Documentation/git-ls-remote.txt | 2 +- Documentation/git-ls-tree.txt | 6 +- Documentation/git-mailinfo.txt | 4 +- Documentation/git-mailsplit.txt | 2 +- Documentation/git-merge-index.txt | 2 +- Documentation/git-mv.txt | 2 +- Documentation/git-name-rev.txt | 10 +- Documentation/git-notes.txt | 4 +- Documentation/git-p4.txt | 26 ++--- Documentation/git-pack-objects.txt | 36 +++--- Documentation/git-patch-id.txt | 6 +- Documentation/git-prune.txt | 2 +- Documentation/git-pull.txt | 6 +- Documentation/git-push.txt | 10 +- Documentation/git-quiltimport.txt | 2 +- Documentation/git-read-tree.txt | 6 +- Documentation/git-rebase.txt | 108 +++++++++--------- Documentation/git-repack.txt | 2 +- Documentation/git-reset.txt | 4 +- Documentation/git-rev-parse.txt | 6 +- Documentation/git-rm.txt | 2 +- Documentation/git-send-email.txt | 42 +++---- Documentation/git-send-pack.txt | 2 +- Documentation/git-show-branch.txt | 2 +- Documentation/git-show-ref.txt | 12 +- Documentation/git-status.txt | 10 +- Documentation/git-submodule.txt | 2 +- Documentation/git-svn.txt | 76 ++++++------ Documentation/git-tag.txt | 4 +- Documentation/git-update-index.txt | 12 +- Documentation/git-update-ref.txt | 6 +- Documentation/git-verify-pack.txt | 2 +- Documentation/git-web--browse.txt | 2 +- Documentation/git-whatchanged.txt | 2 +- Documentation/git.txt | 4 +- Documentation/gitcore-tutorial.txt | 2 +- Documentation/gitdiffcore.txt | 30 ++--- Documentation/gitk.txt | 6 +- Documentation/gittutorial-2.txt | 4 +- Documentation/gittutorial.txt | 4 +- Documentation/gitweb.conf.txt | 6 +- Documentation/howto/revert-branch-rebase.txt | 2 +- .../howto/setup-git-server-over-http.txt | 2 +- Documentation/merge-options.txt | 22 ++-- Documentation/pretty-formats.txt | 12 +- Documentation/pretty-options.txt | 20 ++-- Documentation/rev-list-options.txt | 28 ++--- Documentation/signoff-option.txt | 2 +- Documentation/urls.txt | 4 +- Documentation/user-manual.txt | 4 +- 97 files changed, 479 insertions(+), 479 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 0452db2e67..e7623d967b 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -158,7 +158,7 @@ invocation of `git show`: git show -s --pretty=reference .... -or, on an older version of Git without support for --pretty=reference: +or, on an older version of Git without support for `--pretty=reference`: .... git show -s --date=short --pretty='format:%h (%s, %ad)' diff --git a/Documentation/blame-options.txt b/Documentation/blame-options.txt index 117f4cf806..860e8e2f5c 100644 --- a/Documentation/blame-options.txt +++ b/Documentation/blame-options.txt @@ -50,7 +50,7 @@ include::line-range-format.txt[] --line-porcelain:: Show the porcelain format, but output commit information for each line, not just the first time a commit is referenced. - Implies --porcelain. + Implies `--porcelain`. --incremental:: Show the result incrementally in a format designed for @@ -71,11 +71,11 @@ include::line-range-format.txt[] `-` to make the command read from the standard input). --date :: - Specifies the format used to output dates. If --date is not + Specifies the format used to output dates. If `--date` is not provided, the value of the blame.date config variable is used. If the blame.date config variable is also not set, the iso format is used. For supported values, see the discussion - of the --date option at linkgit:git-log[1]. + of the `--date` option at linkgit:git-log[1]. --[no-]progress:: Progress status is reported on the standard error stream diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt index 2d3331f55c..7556df330c 100644 --- a/Documentation/config/diff.txt +++ b/Documentation/config/diff.txt @@ -113,7 +113,7 @@ diff.relative:: diff.orderFile:: File indicating how to order files within a diff. - See the '-O' option to linkgit:git-diff[1] for details. + See the `-O` option to linkgit:git-diff[1] for details. If `diff.orderFile` is a relative pathname, it is treated as relative to the top of the working tree. diff --git a/Documentation/config/gitcvs.txt b/Documentation/config/gitcvs.txt index 02da427fd9..a188638340 100644 --- a/Documentation/config/gitcvs.txt +++ b/Documentation/config/gitcvs.txt @@ -16,16 +16,16 @@ gitcvs.usecrlfattr:: the attributes force Git to treat a file as text, 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 + will be set with `-kb` mode, which suppresses any newline munging the client might otherwise do. If the attributes do not allow the file type to be determined, then `gitcvs.allBinary` is used. See linkgit:gitattributes[5]. gitcvs.allBinary:: This is used if `gitcvs.usecrlfattr` does not resolve - the correct '-kb' mode to use. If true, all + the correct `-kb` mode to use. If true, all unresolved files are sent to the client in - mode '-kb'. This causes the client to treat them + mode `-kb`. This causes the client to treat them as binary files, which suppresses any newline munging it otherwise might do. Alternatively, if it is set to "guess", then the contents of the file are examined to decide if diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 2db8eacc3e..2615b29cb0 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -13,7 +13,7 @@ You can customize the creation of patch text via the `GIT_EXTERNAL_DIFF` and the `GIT_DIFF_OPTS` environment variables (see linkgit:git[1]). -What the -p option produces is slightly different from the traditional +What the `-p` option produces is slightly different from the traditional diff format: 1. It is preceded with a "git diff" header that looks like this: @@ -149,7 +149,7 @@ Similar to two-line header for traditional 'unified' diff format, `/dev/null` is used to signal created or deleted files. + -However, if the --combined-all-paths option is provided, instead of a +However, if the `--combined-all-paths` option is provided, instead of a two-line from-file/to-file you get a N+1 line from-file/to-file header, where N is the number of parents in the merge commit diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index aa2b5c11f2..13e0753862 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -471,7 +471,7 @@ ifndef::git-format-patch[] that is immediately followed by a tab character inside the initial indent of the line are considered whitespace errors. Exits with non-zero status if problems are found. Not compatible - with --exit-code. + with `--exit-code`. --ws-error-highlight=:: Highlight whitespace errors in the `context`, `old` or `new` @@ -522,10 +522,10 @@ original should remain in the result for Git to consider it a total rewrite (i.e. otherwise the resulting patch will be a series of deletion and insertion mixed together with context lines). + -When used with -M, a totally-rewritten file is also considered as the -source of a rename (usually -M only considers a file that disappeared +When used with `-M`, a totally-rewritten file is also considered as the +source of a rename (usually `-M` only considers a file that disappeared as the source of a rename), and the number `n` controls this aspect of -the -B option (defaults to 50%). `-B20%` specifies that a change with +the `-B` option (defaults to 50%). `-B20%` specifies that a change with addition and deletion compared to 20% or more of the file's size are eligible for being picked up as a possible source of a rename to another file. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 07783deee3..4ccd65c166 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -115,10 +115,10 @@ endif::git-pull[] 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 + auto-following or due to a `--tags` option. However, if tags are fetched due to an explicit refspec (either on the command line or in the remote configuration, for example if the remote - was cloned with the --mirror option), then they are also + was cloned with the `--mirror` option), then they are also subject to pruning. Supplying `--prune-tags` is a shorthand for providing the tag refspec. ifndef::git-pull[] @@ -164,7 +164,7 @@ endif::git-pull[] Fetch all tags from the remote (i.e., fetch remote tags `refs/tags/*` into local tags with the same name), in addition to whatever else would otherwise be fetched. Using this - option alone does not subject tags to pruning, even if --prune + 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`). @@ -215,7 +215,7 @@ ifndef::git-pull[] --recurse-submodules-default=[yes|on-demand]:: This option is used internally to temporarily provide a - non-negative default value for the --recurse-submodules + non-negative default value for the `--recurse-submodules` option. All other methods of configuring fetch's submodule recursion (such as settings in linkgit:gitmodules[5] and linkgit:git-config[1]) override this option, as does @@ -240,7 +240,7 @@ endif::git-pull[] ifndef::git-pull[] -q:: --quiet:: - Pass --quiet to git-fetch-pack and silence any other internally + Pass `--quiet` to git-fetch-pack and silence any other internally used git commands. Progress is not reported to the standard error stream. @@ -267,14 +267,14 @@ endif::git-pull[] --show-forced-updates:: By default, git checks if a branch is force-updated during fetch. This can be disabled through fetch.showForcedUpdates, but - the --show-forced-updates option guarantees this check occurs. + the `--show-forced-updates` option guarantees this check occurs. See linkgit:git-config[1]. --no-show-forced-updates:: By default, git checks if a branch is force-updated during - fetch. Pass --no-show-forced-updates or set fetch.showForcedUpdates + fetch. Pass `--no-show-forced-updates` or set fetch.showForcedUpdates to false to skip this check for performance reasons. If used during - 'git-pull' the --ff-only option will still check for forced updates + 'git-pull' the `--ff-only` option will still check for forced updates before attempting a fast-forward update. See linkgit:git-config[1]. -4:: diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index be5e3ac54b..6a7cb07a8a 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -164,7 +164,7 @@ for "git add --no-all ...", i.e. ignored removed files. true to make this the default behaviour. --ignore-missing:: - This option can only be used together with --dry-run. By using + This option can only be used together with `--dry-run`. By using this option the user can check if any of the given files would be ignored, no matter if they are already present in the work tree or not. diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index 91d9a8601c..f1c8098c0b 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -233,7 +233,7 @@ behavior: adjusting the hunk headers appropriately). --directory=:: - Prepend to all filenames. If a "-p" argument was also passed, + Prepend to all filenames. If a `-p` argument was also passed, it is applied before prepending the new root. + For example, a patch that talks about updating `a/git-gui.sh` to `b/git-gui.sh` diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index a595a0ffee..b477e3c495 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -98,7 +98,7 @@ OPTIONS -a:: Attempt to auto-register archives at `http://mirrors.sourcecontrol.net` - This is particularly useful with the -D option. + This is particularly useful with the `-D` option. -t :: Override the default tempdir. diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 9f8172828d..0af18c9df3 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -77,7 +77,7 @@ OPTIONS linkgit:git-upload-archive[1] for details. --exec=:: - Used with --remote to specify the path to the + Used with `--remote` to specify the path to the 'git-upload-archive' on the remote side. :: diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 94dc9a54f2..271b4ee34e 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -280,7 +280,7 @@ start-point is either a local or remote-tracking branch. --sort=:: Sort based on the key given. Prefix `-` to sort in descending - order of the value. You may use the --sort= option + order of the value. You may use the `--sort=` option multiple times, in which case the last key becomes the primary key. The keys supported are the same as those in `git for-each-ref`. Sort order defaults to the value configured for the diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 53804cad4b..4f1e59a3b2 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -88,19 +88,19 @@ unbundle :: the standard error stream is not directed to a terminal. --all-progress:: - When --stdout is specified then progress report is + When `--stdout` is specified then progress report is displayed during the object count and compression phases but inhibited during the write-out phase. The reason is that in some cases the output stream is directly linked to another command which may wish to display progress status of its own as it processes incoming pack data. - This flag is like --progress except that it forces progress - report for the write-out phase as well even if --stdout is + This flag is like `--progress` except that it forces progress + report for the write-out phase as well even if `--stdout` is used. --all-progress-implied:: - This is used to imply --all-progress whenever progress display - is activated. Unlike --all-progress this flag doesn't actually + This is used to imply `--all-progress` whenever progress display + is activated. Unlike `--all-progress` this flag doesn't actually force any progress display by itself. --version=:: diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 4d33e7be0f..b06d3ae3d9 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -52,7 +52,7 @@ OPTIONS --stage=|all:: Instead of checking out unmerged entries, copy out the files from named stage. must be between 1 and 3. - Note: --stage=all automatically implies --temp. + Note: `--stage=all` automatically implies `--temp`. --temp:: Instead of copying the files to the working directory @@ -88,7 +88,7 @@ $ find . -name '*.h' -print0 | xargs -0 git checkout-index -f -- which will force all existing `*.h` files to be replaced with their cached copies. If an empty command line implied "all", then this would force-refresh everything in the index, which was not the point. But -since 'git checkout-index' accepts --stdin it would be faster to use: +since 'git checkout-index' accepts `--stdin` it would be faster to use: ---------------- $ find . -name '*.h' -print0 | git checkout-index -f -z --stdin @@ -128,7 +128,7 @@ or `.` if there is no stage entry. Paths which only have a stage 0 entry will always be omitted from the output. In both formats RS (the record separator) is newline by default -but will be the null byte if -z was passed on the command line. +but will be the null byte if `-z` was passed on the command line. The temporary file names are always safe strings; they will never contain directory separators or whitespace characters. The path field is always relative to the current directory and the temporary diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index b1a6fe4499..3336b8dace 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -151,13 +151,13 @@ of it"). -B :: Creates the branch `` and start it at ``; if it already exists, then reset it to ``. This is - equivalent to running "git branch" with "-f"; see + equivalent to running "git branch" with `-f`; see linkgit:git-branch[1] for details. -t:: --track:: When creating a new branch, set up "upstream" configuration. See - "--track" in linkgit:git-branch[1] for details. + `--track` in linkgit:git-branch[1] for details. + If no `-b` option is given, the name of the new branch will be derived from the remote-tracking branch, by looking at the local part of diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 5d750314b2..0127f56204 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -126,7 +126,7 @@ effect to your index in a row. indicating that an explicit invocation of `git commit --allow-empty` is required. This option overrides that behavior, allowing empty commits to be preserved automatically - in a cherry-pick. Note that when "--ff" is in effect, empty + in a cherry-pick. Note that when `--ff` is in effect, empty commits that meet the "fast-forward" requirement will be kept even without this option. Note also, that use of this option only keeps commits that were initially empty (i.e. the commit recorded the diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index a7f309dff5..f4246300ae 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -28,8 +28,8 @@ OPTIONS -d:: Normally, when no is specified, git clean will not recurse into untracked directories to avoid removing too much. - Specify -d to have it recurse into such directories as well. - If any paths are specified, -d is irrelevant; all untracked + Specify `-d` to have it recurse into such directories as well. + If any paths are specified, `-d` is irrelevant; all untracked files matching the specified paths (with exceptions for nested git directories mentioned under `--force`) will be removed. @@ -37,9 +37,9 @@ OPTIONS --force:: If the Git configuration variable clean.requireForce is not set to false, 'git clean' will refuse to delete files or directories - unless given -f or -i. Git will refuse to modify untracked + unless given `-f` or `-i`. Git will refuse to modify untracked nested git repositories (directories with a .git subdirectory) - unless a second -f is given. + unless a second `-f` is given. -i:: --interactive:: diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 3fe3810f1c..22334771d1 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -31,7 +31,7 @@ currently active branch. After the clone, a plain `git fetch` without arguments will update all the remote-tracking branches, and a `git pull` without arguments will in addition merge the remote master branch into the -current master branch, if any (this is untrue when "--single-branch" +current master branch, if any (this is untrue when `--single-branch` is given; see below). This default configuration is achieved by creating references to @@ -52,7 +52,7 @@ OPTIONS to save space when possible. + If the repository is specified as a local path (e.g., `/path/to/repo`), -this is the default, and --local is essentially a no-op. If the +this is the default, and `--local` is essentially a no-op. If the repository is specified as a URL, then this flag is ignored (and we never use the local optimizations). Specifying `--no-local` will override the default when `/path/to/repo` is given, using the regular diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt index f58e9c43e6..84a02ac15c 100644 --- a/Documentation/git-column.txt +++ b/Documentation/git-column.txt @@ -29,7 +29,7 @@ OPTIONS syntax in linkgit:git-config[1]. --raw-mode=:: - Same as --mode but take mode encoded as a number. This is mainly used + Same as `--mode` but take mode encoded as a number. This is mainly used by other commands that have already parsed layout mode. --width=:: diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 340c5fbb48..6d0d663b50 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -36,18 +36,18 @@ The content to be committed can be specified in several ways: and the index, again before using the 'commit' command; 3. by listing files as arguments to the 'commit' command - (without --interactive or --patch switch), in which + (without `--interactive` or `--patch` switch), in which case the commit will ignore changes staged in the index, and instead record the current content of the listed files (which must already be known to Git); -4. by using the -a switch with the 'commit' command to automatically +4. by using the `-a` switch with the 'commit' command to automatically "add" changes from all known files (i.e. all files that are already listed in the index) and to automatically "rm" files in the index that have been removed from the working tree, and then perform the actual commit; -5. by using the --interactive or --patch switches with the 'commit' command +5. by using the `--interactive` or `--patch` switches with the 'commit' command to decide one by one which files or hunks should be part of the commit in addition to contents in the index, before finalizing the operation. See the ``Interactive Mode'' section of @@ -84,7 +84,7 @@ OPTIONS -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=[(amend|reword):]:: @@ -134,7 +134,7 @@ See linkgit:git-rebase[1] for details. linkgit:git-rebase[1] for details. --reset-author:: - When used with -C/-c/--amend options, or when committing after a + When used with `-C`/`-c`/`--amend` options, or when committing after a conflicting cherry-pick, declare that the authorship of the resulting commit now belongs to the committer. This also renews the author timestamp. @@ -173,7 +173,7 @@ See linkgit:git-rebase[1] for details. Override the commit author. Specify an explicit author using the standard `A U Thor ` format. Otherwise is assumed to be a pattern and is used to search for an existing - commit by that author (i.e. rev-list --all -i --author=); + commit by that author (i.e. `git rev-list --all -i --author=`); the commit author is then copied from the first such commit found. --date=:: @@ -223,7 +223,7 @@ include::signoff-option.txt[] is primarily for use by foreign SCM interface scripts. --allow-empty-message:: - Like --allow-empty this command is primarily for use by foreign + Like `--allow-empty` this command is primarily for use by foreign SCM interface scripts. It allows you to create a commit with an empty commit message without using plumbing commands like linkgit:git-commit-tree[1]. @@ -337,7 +337,7 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) + -- The mode parameter is optional (defaults to 'all'), and is used to -specify the handling of untracked files; when -u is not used, the +specify the handling of untracked files; when `-u` is not used, the default is 'normal', i.e. show untracked files and directories. The possible options are: diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 4b4cc5c5e8..b93394ea45 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -92,7 +92,7 @@ OPTIONS Like get, but returns all values for a multi-valued key. --get-regexp:: - Like --get-all, but interprets the name as a regular expression and + 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 @@ -337,8 +337,8 @@ ENVIRONMENT GIT_CONFIG:: Take the configuration from the given file instead of .git/config. - Using the "--global" option forces this to ~/.gitconfig. Using the - "--system" option forces this to $(prefix)/etc/gitconfig. + Using the `--global` option forces this to ~/.gitconfig. Using the + `--system` option forces this to $(prefix)/etc/gitconfig. GIT_CONFIG_NOSYSTEM:: Whether to skip reading settings from the system-wide diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index cb9b4d2e46..d12ce08789 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -24,11 +24,11 @@ OPTIONS + count: the number of loose objects + -size: disk space consumed by loose objects, in KiB (unless -H is specified) +size: disk space consumed by loose objects, in KiB (unless `-H` is specified) + in-pack: the number of in-pack objects + -size-pack: disk space consumed by the packs, in KiB (unless -H is specified) +size-pack: disk space consumed by the packs, in KiB (unless `-H` is specified) + prune-packable: the number of loose objects that are also present in the packs. These objects could be pruned using `git prune-packed`. @@ -36,7 +36,7 @@ the packs. These objects could be pruned using `git prune-packed`. garbage: the number of files in object database that are neither valid loose objects nor valid packs + -size-garbage: disk space consumed by garbage files, in KiB (unless -H is +size-garbage: disk space consumed by garbage files, in KiB (unless `-H` is specified) + alternate: absolute path of alternate object databases; may appear diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 00154b6c85..f08ab508af 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -18,7 +18,7 @@ DESCRIPTION Exports a commit from Git to a CVS checkout, making it easier to merge patches from a Git repository into a CVS repository. -Specify the name of a CVS checkout using the -w switch or execute it +Specify the name of a CVS checkout using the `-w` switch or execute it from the root of the CVS working copy. In the latter case GIT_DIR must be defined. See examples below. @@ -40,7 +40,7 @@ OPTIONS -p:: Be pedantic (paranoid) when applying patches. Invokes patch with - --fuzz=0 + `--fuzz=0` -a:: Add authorship information. Adds Author line, and Committer (if @@ -48,7 +48,7 @@ OPTIONS -d:: Set an alternative CVSROOT to use. This corresponds to the CVS - -d parameter. Usually users will not want to set this, except + `-d` parameter. Usually users will not want to set this, except if using CVS in an asymmetric fashion. -f:: @@ -99,7 +99,7 @@ $ git cvsexportcommit -v $ cvs commit -F .msg ------------ -Merge one patch into CVS (-c and -w options). The working directory is within the Git Repo:: +Merge one patch into CVS (`-c` and `-w` options). The working directory is within the Git Repo:: + ------------ $ git cvsexportcommit -v -c -w ~/project_cvs_checkout diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index de1ebed67d..143c726511 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -38,7 +38,7 @@ created by 'git cvsimport'. By default initial import will create and populate "master" branch from the CVS repository's main branch which you're free to work with; after that, you need to 'git merge' incremental imports, or any CVS branches, yourself. It is advisable to specify a named remote via --r to separate and protect the incoming branches. +`-r` to separate and protect the incoming branches. If you intend to set up a shared public repository that all developers can read/write, or if you want to use linkgit:git-cvsserver[1], then you @@ -74,7 +74,7 @@ OPTIONS akin to the way 'git clone' uses 'origin' by default. -o :: - When no remote is specified (via -r) the `HEAD` branch + When no remote is specified (via `-r`) the `HEAD` branch from CVS is imported to the 'origin' branch within the Git repository, as `HEAD` already has a special meaning for Git. When a remote is specified the `HEAD` branch is named @@ -82,7 +82,7 @@ OPTIONS Use this option if you want to import into a different branch. + -Use '-o master' for continuing an import that was initially done by +Use `-o master` for continuing an import that was initially done by the old cvs2git tool. -i:: @@ -91,7 +91,7 @@ the old cvs2git tool. not create them if they do not exist. -k:: - Kill keywords: will extract files with '-kk' from the CVS archive + Kill keywords: will extract files with `-kk` from the CVS archive to avoid noisy changesets. Highly recommended, but off by default to preserve compatibility with early imported trees. @@ -103,7 +103,7 @@ the old cvs2git tool. -p :: Additional options for cvsps. - The options `-u` and '-A' are implicit and should not be used here. + The options `-u` and `-A` are implicit and should not be used here. + If you need to pass multiple options, separate them with a comma. @@ -158,7 +158,7 @@ all along. If a time zone is specified, GIT_AUTHOR_DATE will have the corresponding offset applied. + For convenience, this data is saved to `$GIT_DIR/cvs-authors` -each time the '-A' option is provided and read from that same +each time the `-A` option is provided and read from that same file each time 'git cvsimport' is run. + It is not recommended to use this feature if you intend to diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index 1b1c71ad9d..955bae46c9 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -119,7 +119,7 @@ for example: ------ You can use the 'htpasswd' facility that comes with Apache to make these files, but Apache's MD5 crypt method differs from the one used by most C -library's crypt() function, so don't use the -m option. +library's crypt() function, so don't use the `-m` option. Alternatively you can produce the password with perl's crypt() operator: ----- @@ -312,7 +312,7 @@ ENVIRONMENT These variables obviate the need for command-line options in some circumstances, allowing easier restricted usage through git-shell. -GIT_CVSSERVER_BASE_PATH takes the place of the argument to --base-path. +GIT_CVSSERVER_BASE_PATH takes the place of the argument to `--base-path`. GIT_CVSSERVER_ROOT specifies a single-directory whitelist. The repository must still be configured to allow access through @@ -361,7 +361,7 @@ All the operations required for normal use are supported, including checkout, diff, status, update, log, add, remove, commit. Most CVS command arguments that read CVS tags or revision numbers -(typically -r) work, and also support any git refspec +(typically `-r`) work, and also support any git refspec (tag, branch, commit ID, etc). However, CVS revision numbers for non-default branches are not well emulated, and cvs log does not show tags or branches at @@ -374,7 +374,7 @@ As described elsewhere on this page, the "module" parameter of cvs checkout is interpreted as a branch name, and it becomes the main branch. It remains the main branch for a given sandbox even if you temporarily make another branch sticky with -cvs update -r. Alternatively, the -r argument can indicate +cvs update -r. Alternatively, the `-r` argument can indicate some other branch to actually checkout, even though the module is still the "main" branch. Tradeoffs (as currently implemented): Each new "module" creates a new database on disk with @@ -385,7 +385,7 @@ many operations, like cvs update. If you want to refer to a git refspec that has characters that are not allowed by CVS, you have two options. First, it may just work -to supply the git refspec directly to the appropriate CVS -r argument; +to supply the git refspec directly to the appropriate CVS `-r` argument; some CVS clients don't seem to do much sanity checking of the argument. Second, if that fails, you can use a special character escape mechanism that only uses characters that are valid in CVS tags. A sequence @@ -415,7 +415,7 @@ Alternatively, if `gitcvs.usecrlfattr` config is not enabled or the attributes do not allow automatic detection for a filename, then the server uses the `gitcvs.allBinary` config for the default setting. If `gitcvs.allBinary` is set, then file not otherwise -specified will default to '-kb' mode. Otherwise the `-k` mode +specified will default to `-kb` mode. Otherwise the `-k` mode is left blank. But if `gitcvs.allBinary` is set to "guess", then the correct `-k` mode will be guessed based on the contents of the file. diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index fdc28c041c..2794a2d0c1 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -55,14 +55,14 @@ OPTIONS --base-path=:: Remap all the path requests as relative to the given path. This is sort of "Git root" - if you run 'git daemon' with - '--base-path=/srv/git' on example.com, then if you later try to pull + `--base-path=/srv/git` on example.com, then if you later try to pull 'git://example.com/hello.git', 'git daemon' will interpret the path as `/srv/git/hello.git`. --base-path-relaxed:: - If --base-path is enabled and repo lookup fails, with this option + If `--base-path` is enabled and repo lookup fails, with this option 'git daemon' will attempt to lookup without prefixing the base path. - This is useful for switching to --base-path usage, while still + This is useful for switching to `--base-path` usage, while still allowing the old paths. --interpolated-path=:: @@ -81,16 +81,16 @@ OPTIONS do not have the 'git-daemon-export-ok' file. --inetd:: - Have the server run as an inetd service. Implies --syslog (may be + Have the server run as an inetd service. Implies `--syslog` (may be overridden with `--log-destination=`). - Incompatible with --detach, --port, --listen, --user and --group + Incompatible with `--detach`, `--port`, `--listen`, `--user` and `--group` options. --listen=:: Listen on a specific IP address or hostname. IP addresses can be either an IPv4 address or an IPv6 address if supported. If IPv6 - is not supported, then --listen=hostname is also not supported and - --listen must be given an IPv4 address. + is not supported, then `--listen=hostname` is also not supported and + `--listen` must be given an IPv4 address. Can be given more than once. Incompatible with `--inetd` option. @@ -116,7 +116,7 @@ OPTIONS --log-destination=:: Send log messages to the specified destination. - Note that this option does not imply --verbose, + Note that this option does not imply `--verbose`, thus by default only error conditions will be logged. The must be one of: + @@ -154,7 +154,7 @@ otherwise `stderr`. old connections to time out. --detach:: - Detach from the shell. Implies --syslog. + Detach from the shell. Implies `--syslog`. --pid-file=:: Save the process id in 'file'. Ignored when the daemon @@ -200,7 +200,7 @@ Git configuration files in that directory are readable by ``. is more convenient for clients, but may leak information about the existence of unexported repositories. When informative errors are not enabled, all errors report "access denied" to the - client. The default is --no-informative-errors. + client. The default is `--no-informative-errors`. --access-hook=:: Every time a client connects, first run an external command @@ -219,7 +219,7 @@ it declines the service. :: A directory to add to the whitelist of allowed directories. Unless - --strict-paths is specified this will also include subdirectories + `--strict-paths` is specified this will also include subdirectories of each named directory. SERVICES diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index a88f6ae2c6..a3f015743b 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -22,9 +22,9 @@ abbreviated object name of the most recent commit. The result is a "human-readable" object name which can also be used to identify the commit to other git commands. -By default (without --all or --tags) `git describe` only shows +By default (without `--all` or `--tags`) `git describe` only shows annotated tags. For more information about creating annotated tags -see the -a and -s options to linkgit:git-tag[1]. +see the `-a` and `-s` options to linkgit:git-tag[1]. If the given object refers to a blob, it will be described as `:`, such that the blob can be found @@ -60,7 +60,7 @@ OPTIONS --contains:: Instead of finding the tag that predates the commit, find the tag that comes after the commit, and thus contains it. - Automatically implies --tags. + Automatically implies `--tags`. --abbrev=:: Instead of using the default 7 hexadecimal digits as the @@ -77,7 +77,7 @@ OPTIONS --exact-match:: Only output exact matches (a tag directly references the - supplied commit). This is a synonym for --candidates=0. + supplied commit). This is a synonym for `--candidates=0`. --debug:: Verbosely display information about the searching strategy @@ -110,9 +110,9 @@ OPTIONS excluding respectively "refs/heads/" and "refs/remotes/" prefix; references of other types are never considered. If given multiple times, a list of patterns will be accumulated and tags matching any of the - patterns will be excluded. When combined with --match a tag will be - considered when it matches at least one --match pattern and does not - match any of the --exclude patterns. Use `--no-exclude` to clear and + patterns will be excluded. When combined with `--match` a tag will be + considered when it matches at least one `--match` pattern and does not + match any of the `--exclude` patterns. Use `--no-exclude` to clear and reset the list of patterns. --always:: @@ -150,7 +150,7 @@ Doing a 'git describe' on a tag-name will just show the tag name: [torvalds@g5 git]$ git describe v1.0.4 v1.0.4 -With --all, the command can use branch heads as references, so +With `--all`, the command can use branch heads as references, so the output shows the reference path as well: [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2 @@ -159,7 +159,7 @@ the output shows the reference path as well: [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^ heads/lt/describe-7-g975b -With --abbrev set to 0, the command can be used to find the +With `--abbrev` set to 0, the command can be used to find the closest tagname without any suffix: [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2 diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index 2fc24c542f..b9225cd824 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -18,7 +18,7 @@ DESCRIPTION Compares the content and mode of the blobs found via two tree objects. If there is only one given, the commit is compared with its parents -(see --stdin below). +(see `--stdin` below). Note that 'git diff-tree' can use the tree encapsulated in a commit object. @@ -37,7 +37,7 @@ include::diff-options.txt[] recurse into sub-trees -t:: - show tree entry itself as well as subtrees. Implies -r. + show tree entry itself as well as subtrees. Implies `-r`. --root:: When `--root` is specified the initial commit will be shown as a big @@ -113,7 +113,7 @@ include::pretty-options.txt[] --combined-all-paths:: This flag causes combined diffs (used for merge commits) to list the name of the file from all parents. It thus only has - effect when -c or --cc are specified, and is likely only + effect when `-c` or `--cc` are specified, and is likely only useful if filename changes are detected (i.e. when either rename or copy detection have been requested). diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 7f4c8a8ce7..9f4b46c910 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -48,9 +48,9 @@ files on disk. do not give , it defaults to HEAD. If HEAD does not exist (e.g. unborn branches) and is not given, it shows all staged changes. - --staged is a synonym of --cached. + `--staged` is a synonym of `--cached`. + -If --merge-base is given, instead of using , use the merge base +If `--merge-base` is given, instead of using , use the merge base of and HEAD. `git diff --merge-base A` is equivalent to `git diff $(git merge-base A HEAD)`. @@ -67,7 +67,7 @@ of and HEAD. `git diff --merge-base A` is equivalent to This is to view the changes between two arbitrary . + -If --merge-base is given, use the merge base of the two commits for the +If `--merge-base` is given, use the merge base of the two commits for the "before" side. `git diff --merge-base A B` is equivalent to `git diff $(git merge-base A B) B`. diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 1978dbdc6a..a1c02918f9 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -67,14 +67,14 @@ produced incorrect results if you gave these options. have been completed, or to save the marks table across incremental runs. As is only opened and truncated at completion, the same path can also be safely given to - --import-marks. + `--import-marks`. The file will not be written if no new object has been marked/exported. --import-marks=:: Before processing any input, load the marks specified in . The input file must exist, must be readable, and - must use the same format as produced by --export-marks. + must use the same format as produced by `--export-marks`. --mark-tags:: In addition to labelling blobs and commits with mark ids, also @@ -86,7 +86,7 @@ produced incorrect results if you gave these options. identifiers. + Any commits (or tags) that have already been marked will not be -exported again. If the backend uses a similar --import-marks file, +exported again. If the backend uses a similar `--import-marks` file, this allows for incremental bidirectional exporting of the repository by keeping the marks the same across runs. @@ -130,7 +130,7 @@ by keeping the marks the same across runs. and will make master{tilde}4 no longer have master{tilde}5 as a parent (though both the old master{tilde}4 and new master{tilde}4 will have all the same files). Use - --reference-excluded-parents to instead have the stream + `--reference-excluded-parents` to instead have the stream refer to commits in the excluded range of history by their sha1sum. Note that the resulting stream can only be used by a repository which already contains the necessary parent @@ -160,7 +160,7 @@ by keeping the marks the same across runs. to export. For example, `master~10..master` causes the current master reference to be exported along with all objects added since its 10th ancestor commit and (unless the - --reference-excluded-parents option is specified) all files + `--reference-excluded-parents` option is specified) all files common to master{tilde}9 and master{tilde}10. EXAMPLES diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index 39cfa05b28..ff67238633 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -40,7 +40,7 @@ OPTIONS not contain the old commit). --quiet:: - Disable the output shown by --stats, making fast-import usually + Disable the output shown by `--stats`, making fast-import usually be silent when it is successful. However, if the import stream has directives intended to show user output (e.g. `progress` directives), the corresponding messages will still be shown. @@ -49,7 +49,7 @@ OPTIONS Display some basic statistics about the objects fast-import has created, the packfiles they were stored into, and the memory used by fast-import during this run. Showing this output - is currently the default, but can be disabled with --quiet. + is currently the default, but can be disabled with `--quiet`. --allow-unsafe-features:: Many command-line options can be provided as part of the @@ -97,23 +97,23 @@ Locations of Marks Files have been completed, or to save the marks table across incremental runs. As is only opened and truncated at checkpoint (or completion) the same path can also be - safely given to --import-marks. + safely given to `--import-marks`. --import-marks=:: Before processing any input, load the marks specified in . The input file must exist, must be readable, and - must use the same format as produced by --export-marks. + must use the same format as produced by `--export-marks`. Multiple options may be supplied to import more than one set of marks. If a mark is defined to different values, the last file wins. --import-marks-if-exists=:: - Like --import-marks but instead of erroring out, silently + Like `--import-marks` but instead of erroring out, silently skips the file if it does not exist. --[no-]relative-marks:: - After specifying --relative-marks the paths specified - with --import-marks= and --export-marks= are relative + After specifying `--relative-marks` the paths specified + with `--import-marks`= and `--export-marks`= are relative to an internal directory in the current repository. In git-fast-import this means that the paths are relative to the .git/info/fast-import directory. However, other @@ -217,8 +217,8 @@ fast-forward update, fast-import will skip updating that ref and instead prints a warning message. fast-import will always attempt to update all branch refs, and does not stop on the first failure. -Branch updates can be forced with --force, but it's recommended that -this only be used on an otherwise quiet repository. Using --force +Branch updates can be forced with `--force`, but it's recommended that +this only be used on an otherwise quiet repository. Using `--force` is not necessary for an initial import into an empty repository. @@ -269,11 +269,11 @@ Date Formats ~~~~~~~~~~~~ The following date formats are supported. A frontend should select the format it will use for this import by passing the format name -in the --date-format= command-line option. +in the `--date-format`= command-line option. `raw`:: This is the Git native format and is `