From patchwork Fri Apr 9 04:02:52 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Firmin Martin X-Patchwork-Id: 12194989 Return-Path: Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 3A034C43460 for ; Fri, 9 Apr 2021 04:06:00 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id B43996115C for ; Fri, 9 Apr 2021 04:05:59 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S231440AbhDIEGK (ORCPT ); Fri, 9 Apr 2021 00:06:10 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:60956 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S230219AbhDIEF7 (ORCPT ); Fri, 9 Apr 2021 00:05:59 -0400 Received: from mail-wm1-x32f.google.com (mail-wm1-x32f.google.com [IPv6:2a00:1450:4864:20::32f]) by lindbergh.monkeyblade.net (Postfix) with ESMTPS id 5E8E0C061765 for ; Thu, 8 Apr 2021 21:05:46 -0700 (PDT) Received: by mail-wm1-x32f.google.com with SMTP id p19so2196994wmq.1 for ; Thu, 08 Apr 2021 21:05:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=lU0A+x1PLHQF6NMG3fhiVQnC3HP/G/ubGDZSkmn32Q0=; b=KqgQ5ELEsOAYi87f975M7IhNRIAVb0Hz2Gfo1i5y0A9TZEYS1YQtEPK66k6BS7PL0e /dTYcFhAstJ2wLeEXzfYQZBMiJbaPRXSJQV2f7at8Om7iLih+1BBOHZYwdWe1XBszVbb 6xCLIcRouAB5IhWw5Z6VAAo73IjZSJp083lxCBo09K2mW0AajIJFdVb+LIP8Tyz/1fpD VaMQWmtS+aup2BM3UhadyIwQ+1tKRbxWSkRgiYfNV/BcTbWlqQoI00Rwq09U28Qk5vo4 buBHURGcq8Ff17Gkafesp8bZS0xcHtrGWOxfp/qga7fD8jSjBMN8/9XUwzhaqWaRrKET RDGA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=lU0A+x1PLHQF6NMG3fhiVQnC3HP/G/ubGDZSkmn32Q0=; b=ttOw1CkuvwpCBQ7lv+HB/ZO9ThJ62uQvFEiy42pvLRZrpTFrPbrQHbI/q3ztkvzJBc efVJZwfgRHYsT2SyeLpqa12HX5f1DCKZjLmq9QCEBlipBYTBeVKumx8QwdJ8oE6Ze8AN muAlY0at/gnqy+V+PkIFFsFuARfTcjfgYVsCYA2elSZiLpAESgchP1Wb2xjApO/QDt7m WHsAq2M/aXL4206XI+Q6XlzZUYn8y/PydyigfW6Ah+bbdsOc2/ziijGCIU1B7RQuryS+ LlDqKqpru07QkG+e1+tWf24LRqAHcnv5rVFRpPKfHkD5hHxAB/LrUxoVIQiEtCFdzoon k0Gw== X-Gm-Message-State: AOAM530pydfaIRYF/vnLGjFJqWFKTc/xhQA8lScfjTr3ryaiGbht3Jrb nvVWvtilxI+wtGxn+2Vq6DFRPB9ITy7zdA== X-Google-Smtp-Source: ABdhPJwVwrrcuD0+EemmUDM72yKREbTinUKh2f9OFBqXNz0VPnfrzmGPuIuWkwowRiignuWa3829lQ== X-Received: by 2002:a05:600c:4788:: with SMTP id k8mr7175255wmo.77.1617941142977; Thu, 08 Apr 2021 21:05:42 -0700 (PDT) Received: from Inspiron.home (2a01cb04010c420080e637770dc2ae3c.ipv6.abo.wanadoo.fr. [2a01:cb04:10c:4200:80e6:3777:dc2:ae3c]) by smtp.gmail.com with ESMTPSA id c9sm2064636wrr.78.2021.04.08.21.05.40 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 08 Apr 2021 21:05:41 -0700 (PDT) From: Firmin Martin To: git@vger.kernel.org Cc: Firmin Martin Subject: [RFC PATCH v1 04/13] doc: typeset git-related commands in monospace Date: Fri, 9 Apr 2021 06:02:52 +0200 Message-Id: <20210409040301.3260358-5-firminmartin24@gmail.com> X-Mailer: git-send-email 2.31.1.133.g84d06cdc06 In-Reply-To: <20210409040301.3260358-1-firminmartin24@gmail.com> References: <20210409040301.3260358-1-firminmartin24@gmail.com> MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Wrap git-related commands with backticks as indicated in the CodingGuidelines. Signed-off-by: Firmin Martin --- Documentation/MyFirstContribution.txt | 8 +- Documentation/config.txt | 2 +- Documentation/diff-format.txt | 8 +- Documentation/diff-generate-patch.txt | 4 +- Documentation/diff-options.txt | 8 +- Documentation/fetch-options.txt | 18 +- Documentation/git-add.txt | 6 +- Documentation/git-am.txt | 20 +- Documentation/git-apply.txt | 14 +- Documentation/git-archimport.txt | 12 +- Documentation/git-archive.txt | 6 +- Documentation/git-bisect-lk2009.txt | 164 ++++++++-------- Documentation/git-bisect.txt | 38 ++-- Documentation/git-blame.txt | 10 +- Documentation/git-branch.txt | 28 +-- Documentation/git-bugreport.txt | 4 +- Documentation/git-bundle.txt | 34 ++-- Documentation/git-cat-file.txt | 6 +- Documentation/git-check-attr.txt | 4 +- Documentation/git-check-ignore.txt | 4 +- Documentation/git-check-mailmap.txt | 2 +- Documentation/git-check-ref-format.txt | 8 +- Documentation/git-checkout-index.txt | 10 +- Documentation/git-checkout.txt | 42 ++-- Documentation/git-cherry-pick.txt | 6 +- Documentation/git-cherry.txt | 8 +- Documentation/git-citool.txt | 6 +- Documentation/git-clean.txt | 14 +- Documentation/git-clone.txt | 2 +- Documentation/git-column.txt | 4 +- Documentation/git-commit-graph.txt | 4 +- Documentation/git-commit-tree.txt | 6 +- Documentation/git-commit.txt | 16 +- Documentation/git-config.txt | 42 ++-- Documentation/git-count-objects.txt | 2 +- .../git-credential-cache--daemon.txt | 2 +- Documentation/git-credential-cache.txt | 2 +- Documentation/git-credential-store.txt | 4 +- Documentation/git-credential.txt | 16 +- Documentation/git-cvsexportcommit.txt | 4 +- Documentation/git-cvsimport.txt | 20 +- Documentation/git-cvsserver.txt | 56 +++--- Documentation/git-daemon.txt | 52 ++--- Documentation/git-describe.txt | 22 +-- Documentation/git-diff-files.txt | 4 +- Documentation/git-diff-index.txt | 20 +- Documentation/git-diff-tree.txt | 12 +- Documentation/git-diff.txt | 30 +-- Documentation/git-difftool.txt | 34 ++-- Documentation/git-fast-export.txt | 28 +-- Documentation/git-fast-import.txt | 36 ++-- Documentation/git-fetch-pack.txt | 18 +- Documentation/git-fetch.txt | 14 +- Documentation/git-filter-branch.txt | 92 ++++----- Documentation/git-fmt-merge-msg.txt | 8 +- Documentation/git-for-each-ref.txt | 4 +- Documentation/git-for-each-repo.txt | 2 +- Documentation/git-format-patch.txt | 22 +-- Documentation/git-fsck-objects.txt | 2 +- Documentation/git-fsck.txt | 8 +- Documentation/git-gc.txt | 18 +- Documentation/git-get-tar-commit-id.txt | 8 +- Documentation/git-grep.txt | 10 +- Documentation/git-gui.txt | 24 +-- Documentation/git-hash-object.txt | 6 +- Documentation/git-help.txt | 18 +- Documentation/git-http-backend.txt | 38 ++-- Documentation/git-http-fetch.txt | 6 +- Documentation/git-http-push.txt | 2 +- Documentation/git-imap-send.txt | 4 +- Documentation/git-index-pack.txt | 10 +- Documentation/git-init-db.txt | 2 +- Documentation/git-init.txt | 8 +- Documentation/git-instaweb.txt | 10 +- Documentation/git-interpret-trailers.txt | 10 +- Documentation/git-log.txt | 10 +- Documentation/git-ls-files.txt | 12 +- Documentation/git-ls-remote.txt | 6 +- Documentation/git-ls-tree.txt | 8 +- Documentation/git-mailinfo.txt | 6 +- Documentation/git-mailsplit.txt | 2 +- Documentation/git-maintenance.txt | 2 +- Documentation/git-merge-base.txt | 20 +- Documentation/git-merge-file.txt | 12 +- Documentation/git-merge-index.txt | 10 +- Documentation/git-merge-one-file.txt | 6 +- Documentation/git-merge-tree.txt | 4 +- Documentation/git-merge.txt | 54 +++--- Documentation/git-mergetool--lib.txt | 4 +- Documentation/git-mergetool.txt | 20 +- Documentation/git-mktag.txt | 2 +- Documentation/git-mktree.txt | 2 +- Documentation/git-multi-pack-index.txt | 4 +- Documentation/git-mv.txt | 8 +- Documentation/git-name-rev.txt | 6 +- Documentation/git-notes.txt | 52 ++--- Documentation/git-p4.txt | 132 ++++++------- Documentation/git-pack-objects.txt | 8 +- Documentation/git-pack-redundant.txt | 4 +- Documentation/git-pack-refs.txt | 2 +- Documentation/git-patch-id.txt | 12 +- Documentation/git-prune-packed.txt | 2 +- Documentation/git-prune.txt | 16 +- Documentation/git-pull.txt | 18 +- Documentation/git-push.txt | 24 +-- Documentation/git-quiltimport.txt | 4 +- Documentation/git-range-diff.txt | 2 +- Documentation/git-read-tree.txt | 54 +++--- Documentation/git-rebase.txt | 48 ++--- Documentation/git-receive-pack.txt | 28 +-- Documentation/git-reflog.txt | 12 +- Documentation/git-remote-ext.txt | 26 +-- Documentation/git-remote-fd.txt | 12 +- Documentation/git-remote.txt | 28 +-- Documentation/git-repack.txt | 14 +- Documentation/git-replace.txt | 22 +-- Documentation/git-request-pull.txt | 2 +- Documentation/git-rerere.txt | 34 ++-- Documentation/git-reset.txt | 22 +-- Documentation/git-restore.txt | 6 +- Documentation/git-rev-list.txt | 6 +- Documentation/git-rev-parse.txt | 34 ++-- Documentation/git-revert.txt | 10 +- Documentation/git-rm.txt | 4 +- Documentation/git-send-email.txt | 28 +-- Documentation/git-send-pack.txt | 12 +- Documentation/git-sh-i18n--envsubst.txt | 2 +- Documentation/git-sh-i18n.txt | 2 +- Documentation/git-sh-setup.txt | 2 +- Documentation/git-shell.txt | 24 +-- Documentation/git-shortlog.txt | 10 +- Documentation/git-show-branch.txt | 22 +-- Documentation/git-show-index.txt | 2 +- Documentation/git-show-ref.txt | 8 +- Documentation/git-show.txt | 10 +- Documentation/git-sparse-checkout.txt | 6 +- Documentation/git-stage.txt | 2 +- Documentation/git-stash.txt | 28 +-- Documentation/git-status.txt | 6 +- Documentation/git-stripspace.txt | 8 +- Documentation/git-submodule.txt | 44 ++--- Documentation/git-svn.txt | 176 ++++++++--------- Documentation/git-switch.txt | 10 +- Documentation/git-symbolic-ref.txt | 8 +- Documentation/git-tag.txt | 22 +-- Documentation/git-unpack-file.txt | 2 +- Documentation/git-unpack-objects.txt | 2 +- Documentation/git-update-index.txt | 42 ++-- Documentation/git-update-ref.txt | 2 +- Documentation/git-update-server-info.txt | 2 +- Documentation/git-upload-archive.txt | 8 +- Documentation/git-upload-pack.txt | 8 +- Documentation/git-var.txt | 2 +- Documentation/git-verify-commit.txt | 4 +- Documentation/git-verify-pack.txt | 4 +- Documentation/git-verify-tag.txt | 4 +- Documentation/git-web--browse.txt | 8 +- Documentation/git-whatchanged.txt | 6 +- Documentation/git-worktree.txt | 18 +- Documentation/git-write-tree.txt | 10 +- Documentation/git.txt | 36 ++-- Documentation/gitattributes.txt | 22 +-- Documentation/gitcore-tutorial.txt | 164 ++++++++-------- Documentation/gitcredentials.txt | 8 +- Documentation/gitcvs-migration.txt | 14 +- Documentation/gitdiffcore.txt | 32 ++-- Documentation/giteveryday.txt | 8 +- Documentation/gitfaq.txt | 2 +- Documentation/githooks.txt | 10 +- Documentation/gitignore.txt | 6 +- Documentation/gitk.txt | 24 +-- Documentation/gitmodules.txt | 2 +- Documentation/gitnamespaces.txt | 8 +- Documentation/gitremote-helpers.txt | 32 ++-- Documentation/gitrepository-layout.txt | 22 +-- Documentation/gittutorial-2.txt | 22 +-- Documentation/gittutorial.txt | 56 +++--- Documentation/gitweb.conf.txt | 180 +++++++++--------- Documentation/gitweb.txt | 90 ++++----- Documentation/gitworkflows.txt | 6 +- Documentation/glossary-content.txt | 8 +- Documentation/i18n.txt | 4 +- Documentation/merge-options.txt | 4 +- Documentation/pull-fetch-param.txt | 10 +- Documentation/revisions.txt | 2 +- Documentation/urls-remotes.txt | 12 +- Documentation/urls.txt | 2 +- Documentation/user-manual.txt | 30 +-- 188 files changed, 1731 insertions(+), 1731 deletions(-) diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt index af0a9da62e..06f9f370d7 100644 --- a/Documentation/MyFirstContribution.txt +++ b/Documentation/MyFirstContribution.txt @@ -481,7 +481,7 @@ git-psuh - Delight users' typo with a shy horse SYNOPSIS -------- [verse] -'git-psuh [...]' +`git-psuh [...]` DESCRIPTION ----------- @@ -590,7 +590,7 @@ you the rest of the options afterwards, untouched. Now that you have a usage hint, you can teach Git how to show it in the general command list shown by `git help git` or `git help -a`, which is generated from -`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh' +`command-list.txt`. Find the line for `git-pull` so you can add your `git-psuh` line above it in alphabetical order. Now, we can add some attributes about the command which impacts where it shows up in the aforementioned help commands. The top of `command-list.txt` shares some information about what each attribute @@ -652,7 +652,7 @@ Create a new file `t/t9999-psuh-tutorial.sh`. Begin with the header as so (see test_description='git-psuh test -This test runs git-psuh and makes sure it does not crash.' +This test runs `git-psuh` and makes sure it does not crash.' . ./test-lib.sh ---- @@ -971,7 +971,7 @@ Here's an example body for `psuh`: ---- Our internal metrics indicate widespread interest in the command -git-psuh - that is, many users are trying to use it, but finding it is +`git-psuh` - that is, many users are trying to use it, but finding it is unavailable, using some unknown workaround instead. The following handful of patches add the psuh command and implement some diff --git a/Documentation/config.txt b/Documentation/config.txt index bf82766a6a..05bcf1bf2b 100644 --- a/Documentation/config.txt +++ b/Documentation/config.txt @@ -249,7 +249,7 @@ boolean:: `0` and the empty string. + When converting a value to its canonical form using the `--type=bool` type -specifier, 'git config' will ensure that the output is "true" or +specifier, `git config` will ensure that the output is "true" or "false" (spelled in lowercase). integer:: diff --git a/Documentation/diff-format.txt b/Documentation/diff-format.txt index fbbd410a84..14ef11d552 100644 --- a/Documentation/diff-format.txt +++ b/Documentation/diff-format.txt @@ -1,8 +1,8 @@ Raw output format ----------------- -The raw output format from "git-diff-index", "git-diff-tree", -"git-diff-files" and "git diff --raw" are very similar. +The raw output format from `git-diff-index`, `git-diff-tree`, +`git-diff-files` and `git diff --raw` are very similar. These commands all compare two sets of things; what is compared differs: @@ -19,7 +19,7 @@ git-diff-tree [-r] [...]:: git-diff-files [...]:: compares the index and the files on the filesystem. -The "git-diff-tree" command begins its output by printing the hash of +The `git-diff-tree` command begins its output by printing the hash of what is being compared. After that, all the commands print one output line per changed file. @@ -86,7 +86,7 @@ verbatim and the line is terminated by a NUL byte. diff format for merges ---------------------- -"git-diff-tree", "git-diff-files" and "git-diff --raw" +`git-diff-tree`, `git-diff-files` and `git-diff --raw` can take `-c` or `--cc` option to generate diff output also for merge commits. The output differs from the format described above in the following way: diff --git a/Documentation/diff-generate-patch.txt b/Documentation/diff-generate-patch.txt index 2615b29cb0..da1572b765 100644 --- a/Documentation/diff-generate-patch.txt +++ b/Documentation/diff-generate-patch.txt @@ -16,7 +16,7 @@ You can customize the creation of patch text via the 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: +1. It is preceded with a `git diff` header that looks like this: diff --git a/file1 b/file2 + @@ -117,7 +117,7 @@ index fabadb8,cc95eb0..4866510 for_each_ref(get_name); ------------ -1. It is preceded with a "git diff" header, that looks like +1. It is preceded with a `git diff` header, that looks like this (when the `-c` option is used): diff --combined file diff --git a/Documentation/diff-options.txt b/Documentation/diff-options.txt index 86c19bed1e..34570aa445 100644 --- a/Documentation/diff-options.txt +++ b/Documentation/diff-options.txt @@ -825,10 +825,10 @@ endif::git-format-patch[] Prepend an additional prefix to every line of output. --ita-invisible-in-index:: - By default entries added by "git add -N" appear as an existing - empty file in "git diff" and a new file in "git diff --cached". - This option makes the entry appear as a new file in "git diff" - and non-existent in "git diff --cached". This option could be + By default entries added by `git add -N` appear as an existing + empty file in `git diff` and a new file in `git diff --cached`. + This option makes the entry appear as a new file in `git diff` + and non-existent in `git diff --cached`. This option could be reverted with `--ita-visible-in-index`. Both options are experimental and could be removed in future. diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt index 60a268cc4a..6aa07a54b9 100644 --- a/Documentation/fetch-options.txt +++ b/Documentation/fetch-options.txt @@ -79,7 +79,7 @@ endif::git-pull[] -f:: --force:: - When 'git fetch' is used with `:` refspec it may + When `git fetch` is used with `:` refspec it may refuse to update the local branch as discussed ifdef::git-pull[] in the `` part of the linkgit:git-fetch[1] @@ -223,25 +223,25 @@ ifndef::git-pull[] -u:: --update-head-ok:: - By default 'git fetch' refuses to update the head which + By default `git fetch` refuses to update the head which corresponds to the current branch. This flag disables the - check. This is purely for the internal use for 'git pull' - to communicate with 'git fetch', and unless you are + check. This is purely for the internal use for `git pull` + to communicate with `git fetch`, and unless you are implementing your own Porcelain you are not supposed to use it. 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. ifndef::git-pull[] -q:: --quiet:: - Pass `--quiet` to git-fetch-pack and silence any other internally - used git commands. Progress is not reported to the standard error + Pass `--quiet` to `git-fetch-pack` and silence any other internally + used `git` commands. Progress is not reported to the standard error stream. -v:: @@ -265,13 +265,13 @@ endif::git-pull[] sent to the other side in the order listed on the command line. --show-forced-updates:: - By default, git checks if a branch is force-updated during + 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. See linkgit:git-config[1]. --no-show-forced-updates:: - By default, git checks if a branch is force-updated during + By default, `git` checks if a branch is force-updated during 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 diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 8ec99c5c12..786c31fc60 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -41,7 +41,7 @@ The `git add` command will not add ignored files by default. If any ignored files were explicitly specified on the command line, `git add` will fail with a list of ignored files. Ignored files reached by directory recursion or filename globbing performed by Git (quote your -globs before the shell) will be silently ignored. The 'git add' command can +globs before the shell) will be silently ignored. The `git add` command can be used to add ignored files with the `-f` (force) option. Please see linkgit:git-commit[1] for alternative ways to add content to a @@ -141,8 +141,8 @@ subdirectories). option is a no-op when no is used. + This option is primarily to help users who are used to older -versions of Git, whose "git add ..." was a synonym -for "git add --no-all ...", i.e. ignored removed files. +versions of Git, whose `git add ...` was a synonym +for `git add --no-all ...`, i.e. ignored removed files. -N:: --intent-to-add:: diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index cd56054be0..80f2f89cbd 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -39,13 +39,13 @@ OPTIONS -k:: --keep:: - Pass `-k` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + Pass `-k` flag to `git mailinfo` (see linkgit:git-mailinfo[1]). --keep-non-patch:: - Pass `-b` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + Pass `-b` flag to `git mailinfo` (see linkgit:git-mailinfo[1]). --[no-]keep-cr:: - With `--keep-cr`, call 'git mailsplit' (see linkgit:git-mailsplit[1]) + With `--keep-cr`, call `git mailsplit` (see linkgit:git-mailsplit[1]) with the same option, to prevent it from stripping CR at the end of lines. `am.keepcr` configuration variable can be used to specify the default behaviour. `--no-keep-cr` is useful to override `am.keepcr`. @@ -61,7 +61,7 @@ OPTIONS -m:: --message-id:: - Pass the `-m` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]), + Pass the `-m` flag to `git mailinfo` (see linkgit:git-mailinfo[1]), so that the Message-ID header is added to the commit message. The `am.messageid` configuration variable can be used to specify the default behaviour. @@ -76,7 +76,7 @@ OPTIONS -u:: --utf8:: - Pass `-u` flag to 'git mailinfo' (see linkgit:git-mailinfo[1]). + Pass `-u` flag to `git mailinfo` (see linkgit:git-mailinfo[1]). The proposed commit log message taken from the e-mail is re-coded into UTF-8 encoding (configuration variable `i18n.commitEncoding` can be used to specify project's @@ -86,7 +86,7 @@ This was optional in prior versions of git, but now it is the default. You can use `--no-utf8` to override this. --no-utf8:: - Pass `-n` flag to 'git mailinfo' (see + Pass `-n` flag to `git mailinfo` (see linkgit:git-mailinfo[1]). -3:: @@ -97,7 +97,7 @@ default. You can use `--no-utf8` to override this. it is supposed to apply to and we have those blobs available locally. `--no-3way` can be used to override am.threeWay configuration variable. For more information, - see am.threeWay in linkgit:git-config[1]. + see `am.threeWay` in linkgit:git-config[1]. --rerere-autoupdate:: --no-rerere-autoupdate:: @@ -113,7 +113,7 @@ default. You can use `--no-utf8` to override this. --exclude=:: --include=:: --reject:: - These flags are passed to the 'git apply' (see linkgit:git-apply[1]) + These flags are passed to the `git apply` (see linkgit:git-apply[1]) program that applies the patch. @@ -170,7 +170,7 @@ default. You can use `--no-utf8` to override this. to the screen before exiting. This overrides the standard message informing you to use `--continue` or `--skip` to handle the failure. This is solely - for internal use between 'git rebase' and 'git am'. + for internal use between `git rebase` and `git am`. --abort:: Restore the original branch and abort the patching operation. @@ -231,7 +231,7 @@ names. Before any patches are applied, `ORIG_HEAD` is set to the tip of the current branch. This is useful if you have problems with multiple -commits, like running 'git am' on the wrong branch or an error in the +commits, like running `git am` on the wrong branch or an error in the commits that is more easily fixed by changing the mailbox (e.g. errors in the "From:" lines). diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index f1c8098c0b..a836021d5e 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -51,7 +51,7 @@ OPTIONS --summary:: Instead of applying the patch, output a condensed - summary of information obtained from git diff extended + summary of information obtained from `git diff` extended headers, such as creations, renames and mode changes. Turns off "apply". @@ -92,7 +92,7 @@ OPTIONS with the `--reject` and the `--cached` options. --build-fake-ancestor=:: - Newer 'git diff' output has embedded 'index information' + Newer `git diff` output has embedded 'index information' for each blob to help identify the original version that the patch applies to. When this flag is given, and if the original versions of the blobs are available locally, @@ -106,7 +106,7 @@ the information is read from the current index instead. Apply the patch in reverse. --reject:: - For atomicity, 'git apply' by default fails the whole patch and + For atomicity, `git apply` by default fails the whole patch and does not touch the working tree when some of the hunks do not apply. This option makes it apply the parts of the patch that are applicable, and leave the @@ -133,7 +133,7 @@ linkgit:git-config[1]). ever ignored. --unidiff-zero:: - By default, 'git apply' expects that the patch being + By default, `git apply` expects that the patch being applied is a unified diff with at least one line of context. This provides good safety measures, but breaks down when applying a diff generated with `--unified=0`. To bypass these @@ -144,7 +144,7 @@ discouraged. --apply:: If you use any of the options marked "Turns off - 'apply'" above, 'git apply' reads and outputs the + 'apply'" above, `git apply` reads and outputs the requested information without actually applying the patch. Give this flag after those flags to also apply the patch. @@ -243,7 +243,7 @@ running `git apply --directory=modules/git-gui`. --unsafe-paths:: By default, a patch that affects outside the working area (either a Git controlled working tree, or the current working - directory when "git apply" is used as a replacement of GNU + directory when `git apply` is used as a replacement of GNU patch) is rejected as a mistake (or a mischief). + When `git apply` is used as a "better GNU patch", the user can pass @@ -263,7 +263,7 @@ apply.whitespace:: SUBMODULES ---------- -If the patch contains any changes to submodules then 'git apply' +If the patch contains any changes to submodules then `git apply` treats these changes as follows. If `--index` is specified (explicitly or implicitly), then the submodule diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index 6e2dec5ef1..b5c9e500ca 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -30,17 +30,17 @@ branches that have different roots, it will refuse to run. In that case, edit your parameters to define clearly the scope of the import. -'git archimport' uses `tla` extensively in the background to access the +`git archimport` uses `tla` extensively in the background to access the Arch repository. Make sure you have a recent version of `tla` available in the path. `tla` must -know about the repositories you pass to 'git archimport'. +know about the repositories you pass to `git archimport`. -For the initial import, 'git archimport' expects to find itself in an empty +For the initial import, `git archimport` expects to find itself in an empty directory. To follow the development of a project that uses Arch, rerun -'git archimport' with the same parameters as the initial import to perform +`git archimport` with the same parameters as the initial import to perform incremental imports. -While 'git archimport' will try to create sensible branch names for the +While `git archimport` will try to create sensible branch names for the archives that it imports, it is also possible to specify Git branch names manually. To do so, write a Git branch name after each parameter, separated by a colon. This way, you can shorten the Arch @@ -85,7 +85,7 @@ OPTIONS -o:: Use this for compatibility with old-style branch names used by - earlier versions of 'git archimport'. Old-style branch names + earlier versions of `git archimport`. Old-style branch names were category{litdd}branch, whereas new-style branch names are archive,category{litdd}branch{litdd}version. In both cases, names given on the command-line will override the automatically-generated diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 0af18c9df3..4bd6299046 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -21,13 +21,13 @@ structure for the named tree, and writes it out to the standard output. If is specified it is prepended to the filenames in the archive. -'git archive' behaves differently when given a tree ID versus when +`git archive` behaves differently when given a tree ID versus when given a commit ID or tag ID. In the first case the current time is used as the modification time of each file in the archive. In the latter case the commit time as recorded in the referenced commit object is used instead. Additionally the commit ID is stored in a global extended pax header if the tar format is used; it can be extracted -using 'git get-tar-commit-id'. In ZIP files it is stored as a file +using `git get-tar-commit-id`. In ZIP files it is stored as a file comment. OPTIONS @@ -78,7 +78,7 @@ OPTIONS --exec=:: Used with `--remote` to specify the path to the - 'git-upload-archive' on the remote side. + `git-upload-archive` on the remote side. :: The tree or commit to produce an archive for. diff --git a/Documentation/git-bisect-lk2009.txt b/Documentation/git-bisect-lk2009.txt index 1276424d65..b919b3ea42 100644 --- a/Documentation/git-bisect-lk2009.txt +++ b/Documentation/git-bisect-lk2009.txt @@ -7,16 +7,16 @@ Fighting regressions with git bisect Abstract -------- -"git bisect" enables software users and developers to easily find the +`git bisect` enables software users and developers to easily find the commit that introduced a regression. We show why it is important to -have good tools to fight regressions. We describe how "git bisect" +have good tools to fight regressions. We describe how `git bisect` works from the outside and the algorithms it uses inside. Then we -explain how to take advantage of "git bisect" to improve current -practices. And we discuss how "git bisect" could improve in the +explain how to take advantage of `git bisect` to improve current +practices. And we discuss how `git bisect` could improve in the future. -Introduction to "git bisect" +Introduction to `git bisect` ---------------------------- Git is a Distributed Version Control system (DVCS) created by Linus @@ -36,14 +36,14 @@ properly fix a problem when you only need to check a very small set of changes, than when you don't know where look in the first place. So to help people find commits that introduce a "bad" behavior, the -"git bisect" set of commands was invented. And it follows of course -that in "git bisect" parlance, commits where the "interesting +`git bisect` set of commands was invented. And it follows of course +that in `git bisect` parlance, commits where the "interesting behavior" is present are called "bad" commits, while other commits are called "good" commits. And a commit that introduce the behavior we are interested in is called a "first bad commit". Note that there could be more than one "first bad commit" in the commit space we are searching. -So "git bisect" is designed to help find a "first bad commit". And to +So `git bisect` is designed to help find a "first bad commit". And to be as efficient as possible, it tries to perform a binary search. @@ -133,7 +133,7 @@ time. But this is not the end of the fight yet, as of course it continues after the release. And then this is what Ingo Molnar (a well known Linux kernel -developer) says about his use of git bisect: +developer) says about his use of `git bisect`: _____________ I most actively use it during the merge window (when a lot of trees @@ -152,7 +152,7 @@ Other tools to fight regressions So what are the tools used to fight regressions? They are nearly the same as those used to fight regular bugs. The only specific tools are -test suites and tools similar as "git bisect". +test suites and tools similar as `git bisect`. Test suites are very nice. But when they are used alone, they are supposed to be used so that all the tests are checked after each @@ -180,17 +180,17 @@ emulate a bisection process or you will perhaps bluntly test each commit backward starting from the "bad" commit you have which may be very wasteful. -"git bisect" overview +`git bisect` overview --------------------- Starting a bisection ~~~~~~~~~~~~~~~~~~~~ -The first "git bisect" subcommand to use is "git bisect start" to +The first `git bisect` subcommand to use is `git bisect start` to start the search. Then bounds must be set to limit the commit space. This is done usually by giving one "bad" and at least one -"good" commit. They can be passed in the initial call to "git bisect -start" like this: +"good" commit. They can be passed in the initial call to `git bisect +start` like this: ------------- $ git bisect start [BAD [GOOD...]] @@ -211,7 +211,7 @@ $ git bisect good [COMMIT...] where BAD, GOOD and COMMIT are all names that can be resolved to a commit. -Then "git bisect" will checkout a commit of its choosing and ask the +Then `git bisect` will checkout a commit of its choosing and ask the user to test it, like this: ------------- @@ -224,8 +224,8 @@ Note that the example that we will use is really a toy example, we will be looking for the first commit that has a version like "2.6.26-something", that is the commit that has a "SUBLEVEL = 26" line in the top level Makefile. This is a toy example because there are -better ways to find this commit with Git than using "git bisect" (for -example "git blame" or "git log -S"). +better ways to find this commit with Git than using `git bisect` (for +example `git blame` or `git log -S`). Driving a bisection manually ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -236,7 +236,7 @@ script or a command. If the user is driving it, then at each step of the search, the user will have to test the current commit and say if it is "good" or "bad" -using the "git bisect good" or "git bisect bad" commands respectively +using the `git bisect good` or `git bisect bad` commands respectively that have been described above. For example: ------------- @@ -245,7 +245,7 @@ Bisecting: 5480 revisions left to test after this (roughly 13 steps) [66c0b394f08fd89236515c1c84485ea712a157be] KVM: kill file->f_count abuse in kvm ------------- -And after a few more steps like that, "git bisect" will eventually +And after a few more steps like that, `git bisect` will eventually find a first bad commit: ------------- @@ -287,7 +287,7 @@ index 5cf8258..4492984 100644 # *DOCUMENTATION* ------------- -And when we are finished we can use "git bisect reset" to go back to +And when we are finished we can use `git bisect reset` to go back to the branch we were in before we started bisecting: ------------- @@ -300,10 +300,10 @@ Switched to branch 'master' Driving a bisection automatically ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The other way to drive the bisection process is to tell "git bisect" +The other way to drive the bisection process is to tell `git bisect` to launch a script or command at each bisection step to know if the -current commit is "good" or "bad". To do that, we use the "git bisect -run" command. For example: +current commit is "good" or "bad". To do that, we use the `git bisect +run` command. For example: ------------- $ git bisect start v2.6.27 v2.6.25 @@ -336,19 +336,19 @@ bisect run success ------------- In this example, we passed "grep '^SUBLEVEL = 25' Makefile" as -parameter to "git bisect run". This means that at each step, the grep +parameter to `git bisect run`. This means that at each step, the grep command we passed will be launched. And if it exits with code 0 (that -means success) then git bisect will mark the current state as +means success) then `git bisect` will mark the current state as "good". If it exits with code 1 (or any code between 1 and 127 included, except the special code 125), then the current state will be marked as "bad". -Exit code between 128 and 255 are special to "git bisect run". They +Exit code between 128 and 255 are special to `git bisect run`. They make it stop immediately the bisection process. This is useful for example if the command passed takes too long to complete, because you can kill it with a signal and it will stop the bisection process. -It can also be useful in scripts passed to "git bisect run" to "exit +It can also be useful in scripts passed to `git bisect run` to "exit 255" if some very abnormal situation is detected. Avoiding untestable commits @@ -357,15 +357,15 @@ Avoiding untestable commits Sometimes it happens that the current state cannot be tested, for example if it does not compile because there was a bug preventing it at that time. This is what the special exit code 125 is for. It tells -"git bisect run" that the current commit should be marked as +`git bisect run` that the current commit should be marked as untestable and that another one should be chosen and checked out. -If the bisection process is driven manually, you can use "git bisect -skip" to do the same thing. (In fact the special exit code 125 makes -"git bisect run" use "git bisect skip" in the background.) +If the bisection process is driven manually, you can use `git bisect +skip` to do the same thing. (In fact the special exit code 125 makes +`git bisect run` use `git bisect skip` in the background.) Or if you want more control, you can inspect the current state using -for example "git bisect visualize". It will launch gitk (or "git log" +for example `git bisect visualize`. It will launch gitk (or `git log` if the `DISPLAY` environment variable is not set) to help you find a better bisection point. @@ -374,7 +374,7 @@ happen that the regression you are looking for has been introduced by one of these untestable commits. In this case it's not possible to tell for sure which commit introduced the regression. -So if you used "git bisect skip" (or the run script exited with +So if you used `git bisect skip` (or the run script exited with special code 125) you could get a result like this: ------------- @@ -415,7 +415,7 @@ best bisection commit to test at each step is not so simple. Anyway Linus found and implemented a "truly stupid" algorithm, later improved by Junio Hamano, that works quite well. -So the algorithm used by "git bisect" to find the best bisection +So the algorithm used by `git bisect` to find the best bisection commit when there are no skipped commits is the following: 1) keep only the commits that: @@ -530,7 +530,7 @@ Bisection algorithm debugging ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For any commit graph, you can see the number associated with each -commit using "git rev-list --bisect-all". +commit using `git rev-list --bisect-all`. For example, for the above graph, a command like: @@ -658,7 +658,7 @@ A-B-C-D-E-F O 4 3 2 1 ------------- -but with the algorithm used by git bisect we get: +but with the algorithm used by `git bisect` we get: ------------- 7 7 6 5 @@ -682,7 +682,7 @@ initially supposed. Skip algorithm ~~~~~~~~~~~~~~ -When some commits have been skipped (using "git bisect skip"), then +When some commits have been skipped (using `git bisect skip`), then the bisection algorithm is the same for step 1) to 3). But then we use roughly the following steps: @@ -709,7 +709,7 @@ Skip algorithm discussed After step 7) (in the skip algorithm), we could check if the second commit has been skipped and return it if it is not the case. And in -fact that was the algorithm we used from when "git bisect skip" was +fact that was the algorithm we used from when `git bisect skip` was developed in Git version 1.5.4 (released on February 1st 2008) until Git version 1.6.4 (released July 29th 2009). @@ -852,10 +852,10 @@ usual after this step. Best bisecting practices ------------------------ -Using test suites and git bisect together +Using test suites and `git bisect` together ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you both have a test suite and use git bisect, then it becomes less +If you both have a test suite and use `git bisect`, then it becomes less important to check that all tests pass after each commit. Though of course it is probably a good idea to have some checks to avoid breaking too many things because it could make bisecting other bugs @@ -864,7 +864,7 @@ more difficult. You can focus your efforts to check at a few points (for example rc and beta releases) that all the T test cases pass for all the N configurations. And when some tests don't pass you can use "git -bisect" (or better "git bisect run"). So you should perform roughly: +bisect" (or better `git bisect run`). So you should perform roughly: ------------- c * N * T + b * M * log2(M) tests @@ -879,11 +879,11 @@ you would test everything after each commit. This means that test suites are good to prevent some bugs from being committed and they are also quite good to tell you that you have some bugs. But they are not so good to tell you where some bugs have been -introduced. To tell you that efficiently, git bisect is needed. +introduced. To tell you that efficiently, `git bisect` is needed. The other nice thing with test suites, is that when you have one, you already know how to test for bad behavior. So you can use this -knowledge to create a new test case for "git bisect" when it appears +knowledge to create a new test case for `git bisect` when it appears that there is a regression. So it will be easier to bisect the bug and fix it. And then you can add the test case you just created to your test suite. @@ -893,7 +893,7 @@ subject to a virtuous circle: more tests => easier to create tests => easier to bisect => more tests -So test suites and "git bisect" are complementary tools that are very +So test suites and `git bisect` are complementary tools that are very powerful and efficient when used together. Bisecting build failures @@ -907,7 +907,7 @@ $ git bisect start BAD GOOD $ git bisect run make ------------- -Passing sh -c "some commands" to "git bisect run" +Passing sh -c "some commands" to `git bisect run` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For example: @@ -925,7 +925,7 @@ Finding performance regressions Here is an example script that comes slightly modified from a real world script used by Junio Hamano <<4>>. -This script can be passed to "git bisect run" to find the commit that +This script can be passed to `git bisect run` to find the commit that introduced a performance regression: ------------- @@ -969,7 +969,7 @@ It is also a good idea when using any VCS to have only one small logical change in each commit. The smaller the changes in your commit, the most effective "git -bisect" will be. And you will probably need "git bisect" less in the +bisect" will be. And you will probably need `git bisect` less in the first place, as small changes are easier to review even if they are only reviewed by the committer. @@ -996,7 +996,7 @@ misleading to know the first bad commit if it happens to be such a merge, because people might think that the bug comes from bad conflict resolution when it comes from a semantic change in one branch. -Anyway "git rebase" can be used to linearize history. This can be used +Anyway `git rebase` can be used to linearize history. This can be used either to avoid merging in the first place. Or it can be used to bisect on a linear history instead of the non linear one, as this should give more information in case of a semantic change in one @@ -1016,7 +1016,7 @@ A special work-flow to process regressions can give great results. Here is an example of a work-flow used by Andreas Ericsson: * write, in the test suite, a test script that exposes the regression -* use "git bisect run" to find the commit that introduced it +* use `git bisect run` to find the commit that introduced it * fix the bug that is often made obvious by the previous step * commit both the fix and the test script (and if needed more tests) @@ -1034,7 +1034,7 @@ due to how we now feel about writing tests). _____________ Clearly this work-flow uses the virtuous circle between test suites -and "git bisect". In fact it makes it the standard procedure to deal +and `git bisect`. In fact it makes it the standard procedure to deal with regression. In other messages Andreas says that they also use the "best practices" @@ -1048,7 +1048,7 @@ is making bisecting easier, more useful and standard. Involving QA people and if possible end users ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One nice about "git bisect" is that it is not only a developer +One nice about `git bisect` is that it is not only a developer tool. It can effectively be used by QA people or even end users (if they have access to the source code or if they can get access to all the builds). @@ -1091,7 +1091,7 @@ Here is what Ingo Molnar says about that <<7>>: _____________ i have a fully automated bootup-hang bisection script. It is based on -"git-bisect run". I run the script, it builds and boots kernels fully +`git-bisect run`. I run the script, it builds and boots kernels fully automatically, and when the bootup fails (the script notices that via the serial log, which it continuously watches - or via a timeout, if the system does not come up within 10 minutes it's a "bad" kernel), @@ -1100,28 +1100,28 @@ box. (yeah, i should make use of a managed power outlet to 100% automate it) _____________ -Combining test suites, git bisect and other systems together +Combining test suites, `git bisect` and other systems together ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -We have seen that test suites and git bisect are very powerful when +We have seen that test suites and `git bisect` are very powerful when used together. It can be even more powerful if you can combine them with other systems. For example some test suites could be run automatically at night with some unusual (or even random) configurations. And if a regression is -found by a test suite, then "git bisect" can be automatically +found by a test suite, then `git bisect` can be automatically launched, and its result can be emailed to the author of the first bad -commit found by "git bisect", and perhaps other people too. And a new +commit found by `git bisect`, and perhaps other people too. And a new entry in the bug tracking system could be automatically created too. The future of bisecting ----------------------- -"git replace" +`git replace` ~~~~~~~~~~~~~ -We saw earlier that "git bisect skip" is now using a PRNG to try to +We saw earlier that `git bisect skip` is now using a PRNG to try to avoid areas in the commit graph where commits are untestable. The problem is that sometimes the first bad commit will be in an untestable area. @@ -1177,26 +1177,26 @@ For example: $ git bisect start Z' Y ------------- -If you are using "git bisect run", you can use the same manual fix up -as above, and then start another "git bisect run" in the special -branch. Or as the "git bisect" man page says, the script passed to -"git bisect run" can apply a patch before it compiles and test the +If you are using `git bisect run`, you can use the same manual fix up +as above, and then start another `git bisect run` in the special +branch. Or as the `git bisect` man page says, the script passed to +`git bisect run` can apply a patch before it compiles and test the software <<8>>. The patch should turn a current untestable commits into a testable one. So the testing will result in "good" or "bad" and -"git bisect" will be able to find the first bad commit. And the script +`git bisect` will be able to find the first bad commit. And the script should not forget to remove the patch once the testing is done before exiting from the script. -(Note that instead of a patch you can use "git cherry-pick BFC" to -apply the fix, and in this case you should use "git reset --hard -HEAD^" to revert the cherry-pick after testing and before returning +(Note that instead of a patch you can use `git cherry-pick BFC` to +apply the fix, and in this case you should use `git reset --hard +HEAD` to revert the cherry-pick after testing and before returning from the script.) But the above ways to work around untestable areas are a little bit clunky. Using special branches is nice because these branches can be shared by developers like usual branches, but the risk is that people -will get many such branches. And it disrupts the normal "git bisect" -work-flow. So, if you want to use "git bisect run" completely +will get many such branches. And it disrupts the normal `git bisect` +work-flow. So, if you want to use `git bisect run` completely automatically, you have to add special code in your script to restart bisection in the special branches. @@ -1217,13 +1217,13 @@ With the example above that would give: ...-Y-BBC-X1-X2-X3-X4-X5-X6-BFC-Z ------------- -That's why the "git replace" command was created. Technically it +That's why the `git replace` command was created. Technically it stores replacements "refs" in the "refs/replace/" hierarchy. These "refs" are like branches (that are stored in "refs/heads/") or tags (that are stored in "refs/tags"), and that means that they can automatically be shared like branches or tags among developers. -"git replace" is a very powerful mechanism. It can be used to fix +`git replace` is a very powerful mechanism. It can be used to fix commits in already released history, for example to change the commit message or the author. And it can also be used instead of git "grafts" to link a repository with another old repository. @@ -1232,7 +1232,7 @@ In fact it's this last feature that "sold" it to the Git community, so it is now in the `master` branch of Git's Git repository and it should be released in Git 1.6.5 in October or November 2009. -One problem with "git replace" is that currently it stores all the +One problem with `git replace` is that currently it stores all the replacements refs in "refs/replace/", but it would be perhaps better if the replacement refs that are useful only for bisecting would be in "refs/replace/bisect/". This way the replacement refs could be used @@ -1242,7 +1242,7 @@ be used nearly all the time. Bisecting sporadic bugs ~~~~~~~~~~~~~~~~~~~~~~~ -Another possible improvement to "git bisect" would be to optionally +Another possible improvement to `git bisect` would be to optionally add some redundancy to the tests performed so that it would be more reliable when tracking sporadic bugs. @@ -1250,7 +1250,7 @@ This has been requested by some kernel developers because some bugs called sporadic bugs do not appear in all the kernel builds because they are very dependent on the compiler output. -The idea is that every 3 test for example, "git bisect" could ask the +The idea is that every 3 test for example, `git bisect` could ask the user to test a commit that has already been found to be "good" or "bad" (because one of its descendants or one of its ancestors has been found to be "good" or "bad" respectively). If it happens that a commit @@ -1264,7 +1264,7 @@ on Github that does something like that using Bayesian Search Theory <<9>>: _____________ -BBChop is like 'git bisect' (or equivalent), but works when your bug +BBChop is like `git bisect` (or equivalent), but works when your bug is intermittent. That is, it works in the presence of false negatives (when a version happens to work this time even though it contains the bug). It assumes that there are no false positives (in principle, the @@ -1283,12 +1283,12 @@ other tools, especially test suites, that are generally used to fight regressions. But it might be needed to change some work-flows and (bad) habits to get the most out of it. -Some improvements to the algorithms inside "git bisect" are possible +Some improvements to the algorithms inside `git bisect` are possible and some new features could help in some cases, but overall "git bisect" works already very well, is used a lot, and is already very useful. To back up that last claim, let's give the final word to Ingo Molnar when he was asked by the author how much time does he think -"git bisect" saves him when he uses it: +`git bisect` saves him when he uses it: _____________ a _lot_. @@ -1307,7 +1307,7 @@ manual help or when bisecting multiple, overlapping bugs, it's rarely more than an hour. In fact it's invaluable because there are bugs i would never even -_try_ to debug if it wasn't for git bisect. In the past there were bug +_try_ to debug if it wasn't for `git bisect`. In the past there were bug patterns that were immediately hopeless for me to debug - at best i could send the crash/bug signature to lkml and hope that someone else can think of something. @@ -1316,7 +1316,7 @@ And even if a bisection fails today it tells us something valuable about the bug: that it's non-deterministic - timing or kernel image layout dependent. -So git bisect is unconditional goodness - and feel free to quote that +So `git bisect` is unconditional goodness - and feel free to quote that ;-) _____________ @@ -1325,16 +1325,16 @@ Acknowledgments Many thanks to Junio Hamano for his help in reviewing this paper, for reviewing the patches I sent to the Git mailing list, for discussing -some ideas and helping me improve them, for improving "git bisect" a +some ideas and helping me improve them, for improving `git bisect` a lot and for his awesome work in maintaining and developing Git. Many thanks to Ingo Molnar for giving me very useful information that appears in this paper, for commenting on this paper, for his -suggestions to improve "git bisect" and for evangelizing "git bisect" +suggestions to improve `git bisect` and for evangelizing `git bisect` on the linux kernel mailing lists. Many thanks to Linus Torvalds for inventing, developing and -evangelizing "git bisect", Git and Linux. +evangelizing `git bisect`, Git and Linux. Many thanks to the many other great people who helped one way or another when I worked on Git, especially to Andreas Ericsson, Johannes @@ -1351,7 +1351,7 @@ References - [[[2]]] http://www.oracle.com/technetwork/java/codeconvtoc-136057.html['Code Conventions for the Java Programming Language'. Sun Microsystems.] - [[[3]]] https://en.wikipedia.org/wiki/Software_maintenance['Software maintenance'. Wikipedia.] - [[[4]]] https://lore.kernel.org/git/7vps5xsbwp.fsf_-_@assigned-by-dhcp.cox.net/[Junio C Hamano. 'Automated bisect success story'.] -- [[[5]]] https://lwn.net/Articles/317154/[Christian Couder. 'Fully automated bisecting with "git bisect run"'. LWN.net.] +- [[[5]]] https://lwn.net/Articles/317154/[Christian Couder. 'Fully automated bisecting with `git bisect run`'. LWN.net.] - [[[6]]] https://lwn.net/Articles/277872/[Jonathan Corbet. 'Bisection divides users and developers'. LWN.net.] - [[[7]]] https://lore.kernel.org/lkml/20071207113734.GA14598@elte.hu/[Ingo Molnar. 'Re: BUG 2.6.23-rc3 can't see sd partitions on Alpha'. Linux-kernel mailing list.] - [[[8]]] https://www.kernel.org/pub/software/scm/git/docs/git-bisect.html[Junio C Hamano and the git-list. 'git-bisect(1) Manual Page'. Linux Kernel Archives.] diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index ff50c66e29..d59422636b 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -9,25 +9,25 @@ git-bisect - Use binary search to find the commit that introduced a bug SYNOPSIS -------- [verse] -'git bisect' +`git bisect` DESCRIPTION ----------- The command takes various subcommands, and different options depending on the subcommand: - git bisect start [--term-{new,bad}= --term-{old,good}=] - [--no-checkout] [--first-parent] [ [...]] [--] [...] - git bisect (bad|new|) [] - git bisect (good|old|) [...] - git bisect terms [--term-good | --term-bad] - git bisect skip [(|)...] - git bisect reset [] - git bisect (visualize|view) - git bisect replay - git bisect log - git bisect run ... - git bisect help + `git bisect` start [--term-{new,bad}= --term-{old,good}=] + [--no-checkout] [--first-parent] [ [...]] [--] [...] + `git bisect` (bad|new|) [] + `git bisect` (good|old|) [...] + `git bisect` terms [--term-good | --term-bad] + `git bisect` skip [(|)...] + `git bisect` reset [] + `git bisect` (visualize|view) + `git bisect` replay + `git bisect` log + `git bisect` run ... + `git bisect` help This command uses a binary search algorithm to find which commit in your project's history introduced a bug. You use it by first telling @@ -196,7 +196,7 @@ of `git bisect good` and `git bisect bad` to mark commits. Bisect visualize/view ~~~~~~~~~~~~~~~~~~~~~ -To see the currently remaining suspects in 'gitk', issue the following +To see the currently remaining suspects in `gitk`, issue the following command during the bisection process (the subcommand `view` can be used as an alternative to `visualize`): @@ -204,7 +204,7 @@ as an alternative to `visualize`): $ git bisect visualize ------------ -If the `DISPLAY` environment variable is not set, 'git log' is used +If the `DISPLAY` environment variable is not set, `git log` is used instead. You can also give command-line options such as `-p` and `--stat`. @@ -344,7 +344,7 @@ header file, or "revision that does not have this commit needs this patch applied to work around another problem this bisection is not interested in") applied to the revision being tested. -To cope with such a situation, after the inner 'git bisect' finds the +To cope with such a situation, after the inner `git bisect` finds the next revision to test, the script can apply the patch before compiling, run the real test, and afterwards decide if the revision (possibly with the needed patch) passed the test and then @@ -475,9 +475,9 @@ $ git bisect run sh -c ' $ git bisect reset # quit the bisect session ------------ + -In this case, when 'git bisect run' finishes, bisect/bad will refer to a commit that +In this case, when `git bisect run` finishes, bisect/bad will refer to a commit that has at least one parent whose reachable graph is fully traversable in the sense -required by 'git pack objects'. +required by `git pack objects`. * Look for a fix instead of a regression in the code + @@ -502,7 +502,7 @@ help` or `git bisect -h` to get a long usage description. SEE ALSO -------- -link:git-bisect-lk2009.html[Fighting regressions with git bisect], +link:git-bisect-lk2009.html[Fighting regressions with `git bisect`], linkgit:git-blame[1]. GIT diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 3bf5d5d8b4..aa1b5d56d3 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -8,7 +8,7 @@ git-blame - Show what revision and author last modified each line of a file SYNOPSIS -------- [verse] -'git blame' [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] +`git blame` [-c] [-b] [-l] [--root] [-t] [-f] [-n] [-s] [-e] [-p] [-w] [--incremental] [-L ] [-S ] [-M] [-C] [-C] [-C] [--since=] [--ignore-rev ] [--ignore-revs-file ] [--progress] [--abbrev=] [ | --contents | --reverse ..] @@ -30,7 +30,7 @@ lines that were copied and pasted from another file, etc., see the `-C` and `-M` options. The report does not tell you anything about lines which have been deleted or -replaced; you need to use a tool such as 'git diff' or the "pickaxe" +replaced; you need to use a tool such as `git diff` or the "pickaxe" interface briefly mentioned in the following paragraph. Apart from supporting file annotation, Git also supports searching the @@ -59,7 +59,7 @@ include::blame-options.txt[] file (see `-M`). The first number listed is the score. This is the number of alphanumeric characters detected as having been moved between or within files. This must be above - a certain threshold for 'git blame' to consider those lines + a certain threshold for `git blame` to consider those lines of code to have been moved. -f:: @@ -136,7 +136,7 @@ usage like: SPECIFYING RANGES ----------------- -Unlike 'git blame' and 'git annotate' in older versions of git, the extent +Unlike `git blame` and `git annotate` in older versions of git, the extent of the annotation can be limited to both line ranges and revision ranges. The `-L` option, which limits annotation to a range of lines, may be specified multiple times. @@ -157,7 +157,7 @@ which limits the annotation to the body of the `hello` subroutine. When you are not interested in changes older than version v2.6.18, or changes older than 3 weeks, you can use revision -range specifiers similar to 'git rev-list': +range specifiers similar to `git rev-list`: git blame v2.6.18.. -- foo git blame --since=3.weeks -- foo diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 8ea6e1e523..6f37f11b33 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -8,7 +8,7 @@ git-branch - List, create, or delete branches SYNOPSIS -------- [verse] -'git branch' [--color[=] | --no-color] [--show-current] +`git branch` [--color[=] | --no-color] [--show-current] [-v [--abbrev= | --no-abbrev]] [--column[=] | --no-column] [--sort=] [--merged []] [--no-merged []] @@ -16,13 +16,13 @@ SYNOPSIS [--points-at ] [--format=] [(-r | --remotes) | (-a | --all)] [--list] [...] -'git branch' [--track | --no-track] [-f] [] -'git branch' (--set-upstream-to= | -u ) [] -'git branch' --unset-upstream [] -'git branch' (-m | -M) [] -'git branch' (-c | -C) [] -'git branch' (-d | -D) [-r] ... -'git branch' --edit-description [] +`git branch` [--track | --no-track] [-f] [] +`git branch` (--set-upstream-to= | -u ) [] +`git branch` --unset-upstream [] +`git branch` (-m | -M) [] +`git branch` (-c | -C) [] +`git branch` (-d | -D) [-r] ... +`git branch` --edit-description [] DESCRIPTION ----------- @@ -60,12 +60,12 @@ can leave out at most one of `A` and `B`, in which case it defaults to `HEAD`. Note that this will create the new branch, but it will not switch the -working tree to it; use "git switch " to switch to the +working tree to it; use `git switch ` to switch to the new branch. When a local branch is started off a remote-tracking branch, Git sets up the branch (specifically the `branch..remote` and `branch..merge` -configuration entries) so that 'git pull' will appropriately merge from +configuration entries) so that `git pull` will appropriately merge from the remote-tracking branch. This behavior may be changed via the global `branch.autoSetupMerge` configuration flag. That setting can be overridden by using the `--track` and `--no-track` options, and @@ -87,7 +87,7 @@ has a reflog then the reflog will also be deleted. Use `-r` together with `-d` to delete remote-tracking branches. Note, that it only makes sense to delete remote-tracking branches if they no longer exist -in the remote repository or if 'git fetch' was configured not to fetch +in the remote repository or if `git fetch` was configured not to fetch them again. See also the 'prune' subcommand of linkgit:git-remote[1] for a way to clean up all obsolete remote-tracking branches. @@ -116,7 +116,7 @@ OPTIONS -f:: --force:: Reset to , even if exists - already. Without `-f`, 'git branch' refuses to change an existing branch. + already. Without `-f`, `git branch` refuses to change an existing branch. In combination with `-d` (or `--delete`), allow deleting the branch irrespective of its merged status. In combination with `-m` (or `--move`), allow renaming the branch even if the new @@ -209,7 +209,7 @@ This option is only applicable in non-verbose mode. When creating a new branch, set up `branch..remote` and `branch..merge` configuration entries to mark the start-point branch as "upstream" from the new branch. This - configuration will tell git to show the relationship between the + configuration will tell `git` to show the relationship between the two branches in `git status` and `git branch -v`. Furthermore, it directs `git pull` without arguments to pull from the upstream when the new branch is checked out. @@ -351,7 +351,7 @@ NOTES ----- If you are creating a branch that you want to switch to immediately, -it is easier to use the "git switch" command with its `-c` option to +it is easier to use the `git switch` command with its `-c` option to do the same thing with a single command. The options `--contains`, `--no-contains`, `--merged` and `--no-merged` diff --git a/Documentation/git-bugreport.txt b/Documentation/git-bugreport.txt index 66e88c2e31..bb1355248e 100644 --- a/Documentation/git-bugreport.txt +++ b/Documentation/git-bugreport.txt @@ -25,7 +25,7 @@ The following information is requested from the user: The following information is captured automatically: - - 'git version --build-options' + - `git version --build-options` - uname sysname, release, version, and machine strings - Compiler-specific info string - A list of enabled hooks @@ -46,7 +46,7 @@ OPTIONS -s :: --suffix :: Specify an alternate suffix for the bugreport name, to create a file - named 'git-bugreport-'. This should take the form of a + named `git-bugreport-`. This should take the form of a strftime(3) format string; the current local time will be used. GIT diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 20da47cbd6..fb0ebe1257 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -9,11 +9,11 @@ git-bundle - Move objects and refs by archive SYNOPSIS -------- [verse] -'git bundle' create [-q | --quiet | --progress | --all-progress] [--all-progress-implied] +`git bundle` create [-q | --quiet | --progress | --all-progress] [--all-progress-implied] [--version=] -'git bundle' verify [-q | --quiet] -'git bundle' list-heads [...] -'git bundle' unbundle [...] +`git bundle` verify [-q | --quiet] +`git bundle` list-heads [...] +`git bundle` unbundle [...] DESCRIPTION ----------- @@ -23,9 +23,9 @@ machine be replicated on another machine, but the two machines cannot be directly connected, and therefore the interactive Git protocols (git, ssh, http) cannot be used. -The 'git bundle' command packages objects and references in an archive +The `git bundle` command packages objects and references in an archive at the originating machine, which can then be imported into another -repository using 'git fetch', 'git pull', or 'git clone', +repository using `git fetch`, `git pull`, or `git clone`, after moving the archive by some means (e.g., by sneakernet). As no @@ -40,7 +40,7 @@ OPTIONS create [options] :: Used to create a bundle named 'file'. This requires the '' arguments to define the bundle contents. - 'options' contains the options specific to the 'git bundle create' + 'options' contains the options specific to the `git bundle create` subcommand. verify :: @@ -48,7 +48,7 @@ verify :: cleanly to the current repository. This includes checks on the bundle format itself as well as checking that the prerequisite commits exist and are fully linked in the current repository. - 'git bundle' prints a list of missing commits, if any, and exits + `git bundle` prints a list of missing commits, if any, and exits with a non-zero status. list-heads :: @@ -57,15 +57,15 @@ list-heads :: printed out. unbundle :: - Passes the objects in the bundle to 'git index-pack' + Passes the objects in the bundle to `git index-pack` for storage in the repository, then prints the names of all defined references. If a list of references is given, only references matching those in the list are printed. This command is - really plumbing, intended to be called only by 'git fetch'. + really plumbing, intended to be called only by `git fetch`. :: - A list of arguments, acceptable to 'git rev-parse' and - 'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES + A list of arguments, acceptable to `git rev-parse` and + `git rev-list` (and containing a named ref, see SPECIFYING REFERENCES below), that specifies the specific objects and references to transport. For example, `master~10..master` causes the current `master` reference to be packaged along with all objects @@ -76,10 +76,10 @@ unbundle :: [...]:: A list of references used to limit the references reported as - available. This is principally of use to 'git fetch', which + available. This is principally of use to `git fetch`, which expects to receive only those references asked for and not - necessarily everything in the pack (in this case, 'git bundle' acts - like 'git fetch-pack'). + necessarily everything in the pack (in this case, `git bundle` acts + like `git fetch-pack`). --progress:: Progress status is reported on the standard error stream @@ -117,8 +117,8 @@ unbundle :: SPECIFYING REFERENCES --------------------- -'git bundle' will only package references that are shown by -'git show-ref': this includes heads, tags, and remote heads. References +`git bundle` will only package references that are shown by +`git show-ref`: this includes heads, tags, and remote heads. References such as `master~1` cannot be packaged, but are perfectly suitable for defining the basis. More than one reference may be packaged, and more than one basis can be specified. The objects packaged are those not diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index 4eb0421b3f..3ac3d44fcb 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -9,8 +9,8 @@ git-cat-file - Provide content or type and size information for repository objec SYNOPSIS -------- [verse] -'git cat-file' (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | | --textconv | --filters ) [--path=] -'git cat-file' (--batch[=] | --batch-check[=]) [ --textconv | --filters ] [--follow-symlinks] +`git cat-file` (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | | --textconv | --filters ) [--path=] +`git cat-file` (--batch[=] | --batch-check[=]) [ --textconv | --filters ] [--follow-symlinks] DESCRIPTION ----------- @@ -134,7 +134,7 @@ one in the tree. This option cannot (currently) be used unless `--batch` or `--batch-check` is used. + -For example, consider a git repository containing: +For example, consider a `git` repository containing: + -- f: a file containing "hello\n" diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 84f41a8e82..0ac496700e 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -9,8 +9,8 @@ git-check-attr - Display gitattributes information SYNOPSIS -------- [verse] -'git check-attr' [-a | --all | ...] [--] ... -'git check-attr' --stdin [-z] [-a | --all | ...] +`git check-attr` [-a | --all | ...] [--] ... +`git check-attr` --stdin [-z] [-a | --all | ...] DESCRIPTION ----------- diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index 0c3924a63d..56a4f655c8 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -9,8 +9,8 @@ git-check-ignore - Debug gitignore / exclude files SYNOPSIS -------- [verse] -'git check-ignore' [] ... -'git check-ignore' [] --stdin +`git check-ignore` [] ... +`git check-ignore` [] --stdin DESCRIPTION ----------- diff --git a/Documentation/git-check-mailmap.txt b/Documentation/git-check-mailmap.txt index 02f4418323..302049afe4 100644 --- a/Documentation/git-check-mailmap.txt +++ b/Documentation/git-check-mailmap.txt @@ -9,7 +9,7 @@ git-check-mailmap - Show canonical names and email addresses of contacts SYNOPSIS -------- [verse] -'git check-mailmap' [] ... +`git check-mailmap` [] ... DESCRIPTION diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index f39622c0da..77beb46e98 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -8,10 +8,10 @@ git-check-ref-format - Ensures that a reference name is well formed SYNOPSIS -------- [verse] -'git check-ref-format' [--normalize] +`git check-ref-format` [--normalize] [--[no-]allow-onelevel] [--refspec-pattern] -'git check-ref-format' --branch +`git check-ref-format` --branch DESCRIPTION ----------- @@ -73,7 +73,7 @@ reference name expressions (see linkgit:gitrevisions[7]): . A colon `:` is used as in `srcref:dstref` to mean "use srcref\'s value and store it in dstref" in fetch and push operations. It may also be used to select a specific object such as with - 'git cat-file': "git cat-file blob v1.3.3:refs.c". + `git cat-file`: `git cat-file blob v1.3.3:refs.c`. . at-open-brace `@{` is used as a notation to access a reflog entry. @@ -88,7 +88,7 @@ but it is explicitly forbidden at the beginning of a branch name). When run with `--branch` option in a repository, the input is first expanded for the ``previous checkout syntax'' `@{-n}`. For example, `@{-1}` is a way to refer the last thing that -was checked out using "git switch" or "git checkout" operation. +was checked out using `git switch` or `git checkout` operation. This option should be used by porcelains to accept this syntax anywhere a branch name is expected, so they can act as if you typed the branch name. As an diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index b06d3ae3d9..6e49062ea3 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -9,7 +9,7 @@ git-checkout-index - Copy files from the index to the working tree SYNOPSIS -------- [verse] -'git checkout-index' [-u] [-q] [-a] [-f] [-n] [--prefix=] +`git checkout-index` [-u] [-q] [-a] [-f] [-n] [--prefix=] [--stage=|all] [--temp] [-z] [--stdin] @@ -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 @@ -102,7 +102,7 @@ Using `--` is probably a good policy in scripts. Using --temp or --stage=all --------------------------- When `--temp` is used (or implied by `--stage=all`) -'git checkout-index' will create a temporary file for each index +`git checkout-index` will create a temporary file for each index entry being checked out. The index will not be updated with stat information. These options can be useful if the caller needs all stages of all unmerged entries so that the unmerged files can be @@ -147,9 +147,9 @@ To update and refresh only the files already checked out:: $ git checkout-index -n -f -a && git update-index --ignore-missing --refresh ---------------- -Using 'git checkout-index' to "export an entire tree":: +Using `git checkout-index` to "export an entire tree":: The prefix ability basically makes it trivial to use - 'git checkout-index' as an "export as tree" function. + `git checkout-index` as an "export as tree" function. Just read the desired tree into the index, and do: + ---------------- diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 192dbfe9b0..c3fc807d91 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -8,22 +8,22 @@ git-checkout - Switch branches or restore working tree files SYNOPSIS -------- [verse] -'git checkout' [-q] [-f] [-m] [] -'git checkout' [-q] [-f] [-m] --detach [] -'git checkout' [-q] [-f] [-m] [--detach] -'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] ] [] -'git checkout' [-f|--ours|--theirs|-m|--conflict=