[RFC PATCH v1 04/13] doc: typeset git-related commands in monospace
- From
Firmin Martin <firminmartin24@gmail.com>
- Date
- Apr 9, 2021, 04:02 UTC
- Message-ID
- <20210409040301.3260358-5-firminmartin24@gmail.com>
- In-Reply-To
- <20210409040301.3260358-1-firminmartin24@gmail.com>
Wrap git-related commands with backticks as indicated in the CodingGuidelines.
Signed-off-by: Firmin Martin <firminmartin24@gmail.com> --- 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 [<arg>...]' +`git-psuh [<arg>...]` 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] <tree-ish-1> <tree-ish-2> [<pattern>...]:: git-diff-files [<pattern>...]:: 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 `<src>:<dst>` refspec it may + When `git fetch` is used with `<src>:<dst>` refspec it may refuse to update the local branch as discussed ifdef::git-pull[] in the `<refspec>` 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 <upload-pack>:: When given, and the repository to fetch from is handled - by 'git fetch-pack', `--exec=<upload-pack>` is passed to + by `git fetch-pack`, `--exec=<upload-pack>` 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 <pathspec> is used. + This option is primarily to help users who are used to older -versions of Git, whose "git add <pathspec>..." was a synonym -for "git add --no-all <pathspec>...", i.e. ignored removed files. +versions of Git, whose `git add <pathspec>...` was a synonym +for `git add --no-all <pathspec>...`, 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=<path>:: --include=<path>:: --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=<file>:: - 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 <archive/branch> 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 <archive/branch> 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 <prefix> 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=<git-upload-archive>:: Used with `--remote` to specify the path to the - 'git-upload-archive' on the remote side. + `git-upload-archive` on the remote side. <tree-ish>:: 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<string>"). +better ways to find this commit with Git than using `git bisect` (for +example `git blame` or `git log -S<string>`). 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' <subcommand> <options> +`git bisect` <subcommand> <options> DESCRIPTION ----------- The command takes various subcommands, and different options depending on the subcommand: - git bisect start [--term-{new,bad}=<term> --term-{old,good}=<term>] - [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...] - git bisect (bad|new|<term-new>) [<rev>] - git bisect (good|old|<term-old>) [<rev>...] - git bisect terms [--term-good | --term-bad] - git bisect skip [(<rev>|<range>)...] - git bisect reset [<commit>] - git bisect (visualize|view) - git bisect replay <logfile> - git bisect log - git bisect run <cmd>... - git bisect help + `git bisect` start [--term-{new,bad}=<term> --term-{old,good}=<term>] + [--no-checkout] [--first-parent] [<bad> [<good>...]] [--] [<paths>...] + `git bisect` (bad|new|<term-new>) [<rev>] + `git bisect` (good|old|<term-old>) [<rev>...] + `git bisect` terms [--term-good | --term-bad] + `git bisect` skip [(<rev>|<range>)...] + `git bisect` reset [<commit>] + `git bisect` (visualize|view) + `git bisect` replay <logfile> + `git bisect` log + `git bisect` run <cmd>... + `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 <range>] [-S <revs-file>] [-M] [-C] [-C] [-C] [--since=<date>] [--ignore-rev <rev>] [--ignore-revs-file <file>] [--progress] [--abbrev=<n>] [<rev> | --contents <file> | --reverse <rev>..<rev>] @@ -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[=<when>] | --no-color] [--show-current] +`git branch` [--color[=<when>] | --no-color] [--show-current] [-v [--abbrev=<n> | --no-abbrev]] [--column[=<options>] | --no-column] [--sort=<key>] [--merged [<commit>]] [--no-merged [<commit>]] @@ -16,13 +16,13 @@ SYNOPSIS [--points-at <object>] [--format=<format>] [(-r | --remotes) | (-a | --all)] [--list] [<pattern>...] -'git branch' [--track | --no-track] [-f] <branchname> [<start-point>] -'git branch' (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] -'git branch' --unset-upstream [<branchname>] -'git branch' (-m | -M) [<oldbranch>] <newbranch> -'git branch' (-c | -C) [<oldbranch>] <newbranch> -'git branch' (-d | -D) [-r] <branchname>... -'git branch' --edit-description [<branchname>] +`git branch` [--track | --no-track] [-f] <branchname> [<start-point>] +`git branch` (--set-upstream-to=<upstream> | -u <upstream>) [<branchname>] +`git branch` --unset-upstream [<branchname>] +`git branch` (-m | -M) [<oldbranch>] <newbranch> +`git branch` (-c | -C) [<oldbranch>] <newbranch> +`git branch` (-d | -D) [-r] <branchname>... +`git branch` --edit-description [<branchname>] 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 <newbranch>" to switch to the +working tree to it; use `git switch <newbranch>` 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.<name>.remote` and `branch.<name>.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 <branchname> to <startpoint>, even if <branchname> 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.<name>.remote` and `branch.<name>.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 <format>:: --suffix <format>:: Specify an alternate suffix for the bugreport name, to create a file - named 'git-bugreport-<formatted suffix>'. This should take the form of a + named `git-bugreport-<formatted suffix>`. 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=<version>] <file> <git-rev-list-args> -'git bundle' verify [-q | --quiet] <file> -'git bundle' list-heads <file> [<refname>...] -'git bundle' unbundle <file> [<refname>...] +`git bundle` verify [-q | --quiet] <file> +`git bundle` list-heads <file> [<refname>...] +`git bundle` unbundle <file> [<refname>...] 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] <file> <git-rev-list-args>:: Used to create a bundle named 'file'. This requires the '<git-rev-list-args>' 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 <file>:: @@ -48,7 +48,7 @@ verify <file>:: 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 <file>:: @@ -57,15 +57,15 @@ list-heads <file>:: printed out. unbundle <file>:: - 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`. <git-rev-list-args>:: - 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 <file>:: [<refname>...]:: 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 <file>:: 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 | <type> | --textconv | --filters ) [--path=<path>] <object> -'git cat-file' (--batch[=<format>] | --batch-check[=<format>]) [ --textconv | --filters ] [--follow-symlinks] +`git cat-file` (-t [--allow-unknown-type]| -s [--allow-unknown-type]| -e | -p | <type> | --textconv | --filters ) [--path=<path>] <object> +`git cat-file` (--batch[=<format>] | --batch-check[=<format>]) [ --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 | <attr>...] [--] <pathname>... -'git check-attr' --stdin [-z] [-a | --all | <attr>...] +`git check-attr` [-a | --all | <attr>...] [--] <pathname>... +`git check-attr` --stdin [-z] [-a | --all | <attr>...] 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' [<options>] <pathname>... -'git check-ignore' [<options>] --stdin +`git check-ignore` [<options>] <pathname>... +`git check-ignore` [<options>] --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' [<options>] <contact>... +`git check-mailmap` [<options>] <contact>... 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] <refname> -'git check-ref-format' --branch <branchname-shorthand> +`git check-ref-format` --branch <branchname-shorthand> 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=<string>] +`git checkout-index` [-u] [-q] [-a] [-f] [-n] [--prefix=<string>] [--stage=<number>|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] [<branch>] -'git checkout' [-q] [-f] [-m] --detach [<branch>] -'git checkout' [-q] [-f] [-m] [--detach] <commit> -'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>... -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul] -'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...] +`git checkout` [-q] [-f] [-m] [<branch>] +`git checkout` [-q] [-f] [-m] --detach [<branch>] +`git checkout` [-q] [-f] [-m] [--detach] <commit> +`git checkout` [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>] +`git checkout` [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>... +`git checkout` [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul] +`git checkout` (-p|--patch) [<tree-ish>] [--] [<pathspec>...] DESCRIPTION ----------- Updates files in the working tree to match the version in the index -or the specified tree. If no pathspec was given, 'git checkout' will +or the specified tree. If no pathspec was given, `git checkout` will also update `HEAD` to set the specified branch as the current branch. -'git checkout' [<branch>]:: +`git checkout` [<branch>]:: To prepare for working on `<branch>`, switch to it by updating the index and the files in the working tree, and by pointing `HEAD` at the branch. Local modifications to the files in the @@ -43,12 +43,12 @@ You could omit `<branch>`, in which case the command degenerates to rather expensive side-effects to show only the tracking information, if exists, for the current branch. -'git checkout' -b|-B <new_branch> [<start point>]:: +`git checkout` -b|-B <new_branch> [<start point>]:: Specifying `-b` causes a new branch to be created as if linkgit:git-branch[1] were called and then checked out. In this case you can use the `--track` or `--no-track` options, - which will be passed to 'git branch'. As a convenience, + which will be passed to `git branch`. As a convenience, `--track` without `-b` implies branch creation; see the description of `--track` below. + @@ -60,11 +60,11 @@ $ git branch -f <branch> [<start point>] $ git checkout <branch> ------------ + -that is to say, the branch is not reset/created unless "git checkout" is +that is to say, the branch is not reset/created unless `git checkout` is successful. -'git checkout' --detach [<branch>]:: -'git checkout' [--detach] <commit>:: +`git checkout` --detach [<branch>]:: +`git checkout` [--detach] <commit>:: Prepare to work on top of `<commit>`, by detaching `HEAD` at it (see "DETACHED HEAD" section), and updating the index and the @@ -79,8 +79,8 @@ be used to detach `HEAD` at the tip of the branch (`git checkout + Omitting `<branch>` detaches `HEAD` at the tip of the current branch. -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...:: -'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]:: +`git checkout` [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <pathspec>...:: +`git checkout` [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] --pathspec-from-file=<file> [--pathspec-file-nul]:: Overwrite the contents of the files that match the pathspec. When the `<tree-ish>` (most often a commit) is not given, @@ -96,7 +96,7 @@ specific side of the merge can be checked out of the index by using `--ours` or `--theirs`. With `-m`, changes made to the working tree file can be discarded to re-create the original conflicted merge result. -'git checkout' (-p|--patch) [<tree-ish>] [--] [<pathspec>...]:: +`git checkout` (-p|--patch) [<tree-ish>] [--] [<pathspec>...]:: This is similar to the previous mode, but lets you use the interactive interface to show the "diff" output and choose which hunks to use in the result. See below for the description of @@ -151,7 +151,7 @@ of it"). -B <new_branch>:: Creates the branch `<new_branch>` and start it at `<start_point>`; if it already exists, then reset it to `<start_point>`. 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:: @@ -333,7 +333,7 @@ Note that this option uses the no overlay mode by default (see also any branch (see below for details). + You can use the `@{-N}` syntax to refer to the N-th last -branch/commit checked out using "git checkout" operation. You may +branch/commit checked out using `git checkout` operation. You may also specify `-` which is synonymous to `@{-1}`. + As a special case, you may use `A...B` as a shortcut for the @@ -384,7 +384,7 @@ a---b---c branch 'master' (refers to commit 'c') ------------ When a commit is created in this state, the branch is updated to refer to -the new commit. Specifically, 'git commit' creates a new commit `d`, whose +the new commit. Specifically, `git commit` creates a new commit `d`, whose parent is commit `c`, and then updates branch `master` to refer to new commit `d`. `HEAD` still refers to branch `master` and so indirectly now refers to commit `d`: @@ -493,7 +493,7 @@ $ git tag foo <3> leaving `HEAD` detached. If we have moved away from commit `f`, then we must first recover its object -name (typically by using git reflog), and then we can create a reference to +name (typically by using `git reflog`), and then we can create a reference to it. For example, to see the last two commits to which `HEAD` referred, we can use either of these commands: diff --git a/Documentation/git-cherry-pick.txt b/Documentation/git-cherry-pick.txt index 6069cc77a0..fb12a67778 100644 --- a/Documentation/git-cherry-pick.txt +++ b/Documentation/git-cherry-pick.txt @@ -8,9 +8,9 @@ git-cherry-pick - Apply the changes introduced by some existing commits SYNOPSIS -------- [verse] -'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] +`git cherry-pick` [--edit] [-n] [-m parent-number] [-s] [-x] [--ff] [-S[<keyid>]] <commit>... -'git cherry-pick' (--continue | --skip | --abort | --quit) +`git cherry-pick` (--continue | --skip | --abort | --quit) DESCRIPTION ----------- @@ -52,7 +52,7 @@ OPTIONS -e:: --edit:: - With this option, 'git cherry-pick' will let you edit the commit + With this option, `git cherry-pick` will let you edit the commit message prior to committing. --cleanup=<mode>:: diff --git a/Documentation/git-cherry.txt b/Documentation/git-cherry.txt index 4374f398fa..ab55060668 100644 --- a/Documentation/git-cherry.txt +++ b/Documentation/git-cherry.txt @@ -8,7 +8,7 @@ git-cherry - Find commits yet to be applied to upstream SYNOPSIS -------- [verse] -'git cherry' [-v] [<upstream> [<head> [<limit>]]] +`git cherry` [-v] [<upstream> [<head> [<limit>]]] DESCRIPTION ----------- @@ -16,7 +16,7 @@ Determine whether there are commits in `<head>..<upstream>` that are equivalent to those in the range `<limit>..<head>`. The equivalence test is based on the diff, after removing whitespace -and line numbers. git-cherry therefore detects when commits have been +and line numbers. `git-cherry` therefore detects when commits have been "copied" by means of linkgit:git-cherry-pick[1], linkgit:git-am[1] or linkgit:git-rebase[1]. @@ -45,7 +45,7 @@ EXAMPLES Patch workflows ~~~~~~~~~~~~~~~ -git-cherry is frequently used in patch-based workflows (see +`git-cherry` is frequently used in patch-based workflows (see linkgit:gitworkflows[7]) to determine if a series of patches has been applied by the upstream maintainer. In such a workflow you might create and send a topic branch like this: @@ -85,7 +85,7 @@ $ git log --graph --oneline --decorate --boundary origin/master...topic o 1234567 branch point ------------ -In such cases, git-cherry shows a concise summary of what has yet to +In such cases, `git-cherry` shows a concise summary of what has yet to be applied: ------------ diff --git a/Documentation/git-citool.txt b/Documentation/git-citool.txt index c7a11c36c1..f750f754ae 100644 --- a/Documentation/git-citool.txt +++ b/Documentation/git-citool.txt @@ -8,16 +8,16 @@ git-citool - Graphical alternative to git-commit SYNOPSIS -------- [verse] -'git citool' +`git citool` DESCRIPTION ----------- A Tcl/Tk based graphical interface to review modified files, stage them into the index, enter a commit message and record the new commit onto the current branch. This interface is an alternative -to the less interactive 'git commit' program. +to the less interactive `git commit` program. -'git citool' is actually a standard alias for `git gui citool`. +`git citool` is actually a standard alias for `git gui citool`. See linkgit:git-gui[1] for more details. GIT diff --git a/Documentation/git-clean.txt b/Documentation/git-clean.txt index cbec3e649a..7923ae27a5 100644 --- a/Documentation/git-clean.txt +++ b/Documentation/git-clean.txt @@ -8,7 +8,7 @@ git-clean - Remove untracked files from the working tree SYNOPSIS -------- [verse] -'git clean' [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>... +`git clean` [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>... DESCRIPTION ----------- @@ -26,19 +26,19 @@ are affected. OPTIONS ------- -d:: - Normally, when no <path> is specified, git clean will not + Normally, when no <path> 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 files matching the specified paths (with exceptions for nested - git directories mentioned under `--force`) will be removed. + `git` directories mentioned under `--force`) will be removed. -f:: --force:: If the Git configuration variable `clean.requireForce` is not set - to false, 'git clean' will refuse to delete files or directories + to false, `git clean` will refuse to delete files or directories unless given `-f` or `-i`. Git will refuse to modify untracked - nested git repositories (directories with a .git subdirectory) + nested `git` repositories (directories with a .git subdirectory) unless a second `-f` is given. -i:: @@ -65,7 +65,7 @@ OPTIONS still use the ignore rules given with `-e` options from the command line. This allows removing all untracked files, including build products. This can be used (possibly in - conjunction with 'git restore' or 'git reset') to create a pristine + conjunction with `git restore` or `git reset`) to create a pristine working directory to test a clean build. -X:: @@ -131,7 +131,7 @@ quit:: help:: - Show brief usage of interactive git-clean. + Show brief usage of interactive `git-clean`. SEE ALSO -------- diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt index 8cd602a852..b8ca823467 100644 --- a/Documentation/git-clone.txt +++ b/Documentation/git-clone.txt @@ -9,7 +9,7 @@ git-clone - Clone a repository into a new directory SYNOPSIS -------- [verse] -'git clone' [--template=<template_directory>] +`git clone` [--template=<template_directory>] [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror] [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>] [--dissociate] [--separate-git-dir <git dir>] diff --git a/Documentation/git-column.txt b/Documentation/git-column.txt index ab545fc52d..0865d22bdc 100644 --- a/Documentation/git-column.txt +++ b/Documentation/git-column.txt @@ -8,14 +8,14 @@ git-column - Display data in columns SYNOPSIS -------- [verse] -'git column' [--command=<name>] [--[raw-]mode=<mode>] [--width=<width>] +`git column` [--command=<name>] [--[raw-]mode=<mode>] [--width=<width>] [--indent=<string>] [--nl=<string>] [--padding=<n>] DESCRIPTION ----------- This command formats the lines of its standard input into a table with multiple columns. Each input line occupies one cell of the table. It -is used internally by other git commands to format output into +is used internally by other `git` commands to format output into columns. OPTIONS diff --git a/Documentation/git-commit-graph.txt b/Documentation/git-commit-graph.txt index e1f48c95b3..3246616b10 100644 --- a/Documentation/git-commit-graph.txt +++ b/Documentation/git-commit-graph.txt @@ -9,8 +9,8 @@ git-commit-graph - Write and verify Git commit-graph files SYNOPSIS -------- [verse] -'git commit-graph verify' [--object-dir <dir>] [--shallow] [--[no-]progress] -'git commit-graph write' <options> [--object-dir <dir>] [--[no-]progress] +`git commit-graph verify` [--object-dir <dir>] [--shallow] [--[no-]progress] +`git commit-graph write` <options> [--object-dir <dir>] [--[no-]progress] DESCRIPTION diff --git a/Documentation/git-commit-tree.txt b/Documentation/git-commit-tree.txt index b76a825c94..48a76dd029 100644 --- a/Documentation/git-commit-tree.txt +++ b/Documentation/git-commit-tree.txt @@ -9,8 +9,8 @@ git-commit-tree - Create a new commit object SYNOPSIS -------- [verse] -'git commit-tree' <tree> [(-p <parent>)...] -'git commit-tree' [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] +`git commit-tree` <tree> [(-p <parent>)...] +`git commit-tree` [(-p <parent>)...] [-S[<keyid>]] [(-m <message>)...] [(-F <file>)...] <tree> @@ -77,7 +77,7 @@ A commit encapsulates: - committer name and email and the commit time. A commit comment is read from stdin. If a changelog -entry is not provided via "<" redirection, 'git commit-tree' will just wait +entry is not provided via "<" redirection, `git commit-tree` will just wait for one to be entered and terminated with ^D. include::date-formats.txt[] diff --git a/Documentation/git-commit.txt b/Documentation/git-commit.txt index 6d10f2bdc7..3b22ba718c 100644 --- a/Documentation/git-commit.txt +++ b/Documentation/git-commit.txt @@ -8,7 +8,7 @@ git-commit - Record changes to the repository SYNOPSIS -------- [verse] -'git commit' [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] +`git commit` [-a | --interactive | --patch] [-s] [-v] [-u<mode>] [--amend] [--dry-run] [(-c | -C | --squash) <commit> | --fixup [(amend|reword):]<commit>)] [-F <file> | -m <msg>] [--reset-author] [--allow-empty] [--allow-empty-message] [--no-verify] [-e] [--author=<author>] @@ -58,7 +58,7 @@ summary of what is included by any of the above for the next commit by giving the same set of parameters (options and paths). If you make a commit and then find a mistake immediately after -that, you can recover from it with 'git reset'. +that, you can recover from it with `git reset`. :git-commit: 1 @@ -310,7 +310,7 @@ FROM UPSTREAM REBASE" section in linkgit:git-rebase[1].) of the paths specified on the command line, disregarding any contents that have been staged for other paths. This is the default mode of operation of - 'git commit' if any paths are given on the command line, + `git commit` if any paths are given on the command line, in which case this option can be omitted. If this option is specified together with `--amend`, then no paths need to be specified, which can be used to amend @@ -409,10 +409,10 @@ EXAMPLES -------- When recording your own work, the contents of modified files in your working tree are temporarily stored to a staging area -called the "index" with 'git add'. A file can be +called the "index" with `git add`. A file can be reverted back, only in the index but not in the working tree, to that of the last commit with `git restore --staged <file>`, -which effectively reverts 'git add' and prevents the changes to +which effectively reverts `git add` and prevents the changes to this file from participating in the next commit. After building the state to be committed incrementally with these commands, `git commit` (without any pathname parameter) is used to record what @@ -468,13 +468,13 @@ $ git commit this second commit would record the changes to `hello.c` and `hello.h` as expected. -After a merge (initiated by 'git merge' or 'git pull') stops +After a merge (initiated by `git merge` or `git pull`) stops because of conflicts, cleanly merged paths are already staged to be committed for you, and paths that conflicted are left in unmerged state. You would have to first -check which paths are conflicting with 'git status' +check which paths are conflicting with `git status` and after fixing them manually in your working tree, you would -stage the result as usual with 'git add': +stage the result as usual with `git add`: ------------ $ git status | grep unmerged diff --git a/Documentation/git-config.txt b/Documentation/git-config.txt index 606411c816..85e02aff92 100644 --- a/Documentation/git-config.txt +++ b/Documentation/git-config.txt @@ -9,21 +9,21 @@ git-config - Get and set repository or global options SYNOPSIS -------- [verse] -'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]] -'git config' [<file-option>] [--type=<type>] --add name value -'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern] -'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern] -'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL -'git config' [<file-option>] [--fixed-value] --unset name [value-pattern] -'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern] -'git config' [<file-option>] --rename-section old_name new_name -'git config' [<file-option>] --remove-section name -'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list -'git config' [<file-option>] --get-color name [default] -'git config' [<file-option>] --get-colorbool name [stdout-is-tty] -'git config' [<file-option>] -e | --edit +`git config` [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]] +`git config` [<file-option>] [--type=<type>] --add name value +`git config` [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern] +`git config` [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern] +`git config` [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern] +`git config` [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern] +`git config` [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL +`git config` [<file-option>] [--fixed-value] --unset name [value-pattern] +`git config` [<file-option>] [--fixed-value] --unset-all name [value-pattern] +`git config` [<file-option>] --rename-section old_name new_name +`git config` [<file-option>] --remove-section name +`git config` [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list +`git config` [<file-option>] --get-color name [default] +`git config` [<file-option>] --get-colorbool name [stdout-is-tty] +`git config` [<file-option>] -e | --edit DESCRIPTION ----------- @@ -41,7 +41,7 @@ prepend a single exclamation mark in front (see also <<EXAMPLES>>), but note that this only works when the `--fixed-value` option is not in use. -The `--type=<type>` option instructs 'git config' to ensure that incoming and +The `--type=<type>` option instructs `git config` to ensure that incoming and outgoing values are canonicalize-able under the given <type>. If no `--type=<type>` is given, no canonicalization will be performed. Callers may unset an existing `--type` specifier with `--no-type`. @@ -175,7 +175,7 @@ See also <<FILES>>. is exactly equal to the `value-pattern`. --type <type>:: - 'git config' will ensure that any input or output is valid under the given + `git config` will ensure that any input or output is valid under the given type constraint(s), and will canonicalize outgoing values in `<type>`'s canonical form. + @@ -209,7 +209,7 @@ Valid `<type>`'s include: --no-type:: Un-sets the previously set type specifier (if one was previously set). This - option requests that 'git config' not canonicalize the retrieved variable. + option requests that `git config` not canonicalize the retrieved variable. `--no-type` has no effect without `--type=<type>` or `--<type>`. -z:: @@ -284,7 +284,7 @@ FILES ----- If not set explicitly with `--file`, there are four files where -'git config' will search for configuration options: +`git config` will search for configuration options: $(prefix)/etc/gitconfig:: System-wide configuration file. @@ -311,7 +311,7 @@ $GIT_DIR/config.worktree:: If no further options are given, all reading options will read all of these files that are available. If the global or the system-wide configuration file are not available they will be ignored. If the repository configuration -file is not available or readable, 'git config' will exit with a non-zero +file is not available or readable, `git config` will exit with a non-zero error code. However, in neither case will an error message be issued. The files are read in the order given above, with last value found taking @@ -358,7 +358,7 @@ GIT_CONFIG_VALUE_<n>:: in configuration files, but will be overridden by any explicit options passed via `git -c`. + -This is useful for cases where you want to spawn multiple git commands +This is useful for cases where you want to spawn multiple `git` commands with a common configuration but cannot depend on a configuration file, for example when writing scripts. diff --git a/Documentation/git-count-objects.txt b/Documentation/git-count-objects.txt index d12ce08789..a52bd618c4 100644 --- a/Documentation/git-count-objects.txt +++ b/Documentation/git-count-objects.txt @@ -8,7 +8,7 @@ git-count-objects - Count unpacked number of objects and their disk consumption SYNOPSIS -------- [verse] -'git count-objects' [-v] [-H | --human-readable] +`git count-objects` [-v] [-H | --human-readable] DESCRIPTION ----------- diff --git a/Documentation/git-credential-cache--daemon.txt b/Documentation/git-credential-cache--daemon.txt index 7051c6bdf8..ed4d4c4f35 100644 --- a/Documentation/git-credential-cache--daemon.txt +++ b/Documentation/git-credential-cache--daemon.txt @@ -8,7 +8,7 @@ git-credential-cache--daemon - Temporarily store user credentials in memory SYNOPSIS -------- [verse] -git credential-cache--daemon [--debug] <socket> +`git credential-cache--daemon` [--debug] <socket> DESCRIPTION ----------- diff --git a/Documentation/git-credential-cache.txt b/Documentation/git-credential-cache.txt index b1a9d9b29a..e9834b8b95 100644 --- a/Documentation/git-credential-cache.txt +++ b/Documentation/git-credential-cache.txt @@ -8,7 +8,7 @@ git-credential-cache - Helper to temporarily store passwords in memory SYNOPSIS -------- ----------------------------- -git config credential.helper 'cache [<options>]' +`git config` credential.helper 'cache [<options>]' ----------------------------- DESCRIPTION diff --git a/Documentation/git-credential-store.txt b/Documentation/git-credential-store.txt index 76b0798856..376b0d6c5f 100644 --- a/Documentation/git-credential-store.txt +++ b/Documentation/git-credential-store.txt @@ -8,7 +8,7 @@ git-credential-store - Helper to store credentials on disk SYNOPSIS -------- ------------------- -git config credential.helper 'store [<options>]' +`git config` credential.helper 'store [<options>]' ------------------- DESCRIPTION @@ -45,7 +45,7 @@ FILES ----- If not set explicitly with `--file`, there are two files where -git-credential-store will search for credentials in order of precedence: +`git-credential-store` will search for credentials in order of precedence: ~/.git-credentials:: User-specific credentials file. diff --git a/Documentation/git-credential.txt b/Documentation/git-credential.txt index 31c81c4c02..9bfcb3f90a 100644 --- a/Documentation/git-credential.txt +++ b/Documentation/git-credential.txt @@ -8,7 +8,7 @@ git-credential - Retrieve and store user credentials SYNOPSIS -------- ------------------ -git credential <fill|approve|reject> +`git credential` <fill|approve|reject> ------------------ DESCRIPTION @@ -16,28 +16,28 @@ DESCRIPTION Git has an internal interface for storing and retrieving credentials from system-specific helpers, as well as prompting the user for -usernames and passwords. The git-credential command exposes this +usernames and passwords. The `git-credential` command exposes this interface to scripts which may want to retrieve, store, or prompt for credentials in the same manner as Git. The design of this scriptable interface models the internal C API; see credential.h for more background on the concepts. -git-credential takes an "action" option on the command-line (one of +`git-credential` takes an "action" option on the command-line (one of `fill`, `approve`, or `reject`) and reads a credential description on stdin (see <<IOFMT,INPUT/OUTPUT FORMAT>>). -If the action is `fill`, git-credential will attempt to add "username" +If the action is `fill`, `git-credential` will attempt to add "username" and "password" attributes to the description by reading config files, by contacting any configured credential helpers, or by prompting the user. The username and password attributes of the credential description are then printed to stdout together with the attributes already provided. -If the action is `approve`, git-credential will send the description +If the action is `approve`, `git-credential` will send the description to any configured credential helpers, which may store the credential for later use. -If the action is `reject`, git-credential will send the description to +If the action is `reject`, `git-credential` will send the description to any configured credential helpers, which may erase any stored credential matching the description. @@ -46,7 +46,7 @@ If the action is `approve` or `reject`, no output should be emitted. TYPICAL USE OF GIT CREDENTIAL ----------------------------- -An application using git-credential will typically use `git +An application using `git-credential` will typically use `git credential` following these steps: 1. Generate a credential description based on the context. @@ -61,7 +61,7 @@ information it has): host=example.com path=foo.git - 2. Ask git-credential to give us a username and password for this + 2. Ask `git-credential` to give us a username and password for this description. This is done by running `git credential fill`, feeding the description from step (1) to its standard input. The complete credential description (including the credential per se, i.e. the diff --git a/Documentation/git-cvsexportcommit.txt b/Documentation/git-cvsexportcommit.txt index 76b16f9dae..596512ec73 100644 --- a/Documentation/git-cvsexportcommit.txt +++ b/Documentation/git-cvsexportcommit.txt @@ -9,7 +9,7 @@ git-cvsexportcommit - Export a single commit to a CVS checkout SYNOPSIS -------- [verse] -'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] +`git cvsexportcommit` [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot] [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID @@ -28,7 +28,7 @@ by default. Supports file additions, removals, and commits that affect binary files. -If the commit is a merge commit, you must tell 'git cvsexportcommit' what +If the commit is a merge commit, you must tell `git cvsexportcommit` what parent the changeset should be done against. OPTIONS diff --git a/Documentation/git-cvsimport.txt b/Documentation/git-cvsimport.txt index 95fa94de74..586184bbd4 100644 --- a/Documentation/git-cvsimport.txt +++ b/Documentation/git-cvsimport.txt @@ -9,7 +9,7 @@ git-cvsimport - Salvage your data out of another SCM people love to hate SYNOPSIS -------- [verse] -'git cvsimport' [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] +`git cvsimport` [-o <branch-for-HEAD>] [-h] [-v] [-d <CVSROOT>] [-A <author-conv-file>] [-p <options-for-cvsps>] [-P <file>] [-C <git_repository>] [-z <fuzz>] [-i] [-k] [-u] [-s <subst>] [-a] [-m] [-M <regex>] [-S <regex>] [-L <commitlimit>] @@ -34,9 +34,9 @@ At least version 2.1 is required. Please see the section <<issues,ISSUES>> for further reference. You should *never* do any work of your own on the branches that are -created by 'git cvsimport'. By default initial import will create and populate a +created by `git cvsimport`. By default initial import will create and populate a `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 +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. @@ -55,13 +55,13 @@ OPTIONS -d <CVSROOT>:: The root of the CVS archive. May be local (a simple path) or remote; currently, only the :local:, :ext: and :pserver: access methods - are supported. If not given, 'git cvsimport' will try to read it + are supported. If not given, `git cvsimport` will try to read it from `CVS/Root`. If no such file exists, it checks for the `CVSROOT` environment variable. <CVS_module>:: The CVS module you want to import. Relative to <CVSROOT>. - If not given, 'git cvsimport' tries to read it from + If not given, `git cvsimport` tries to read it from `CVS/Repository`. -C <target-dir>:: @@ -71,14 +71,14 @@ OPTIONS -r <remote>:: The Git remote to import this CVS repository into. Moves all CVS branches into remotes/<remote>/<branch> - akin to the way 'git clone' uses `origin` by default. + akin to the way `git clone` uses `origin` by default. -o <branch-for-HEAD>:: 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 - remotes/<remote>/master mirroring 'git clone' behaviour. + remotes/<remote>/master mirroring `git clone` behaviour. Use this option if you want to import into a different branch. + @@ -152,18 +152,18 @@ This option can be used several times to provide several detection regexes. --------- + -'git cvsimport' will make it appear as those authors had +`git cvsimport` will make it appear as those authors had their GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL set properly 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 -file each time 'git cvsimport' is run. +file each time `git cvsimport` is run. + It is not recommended to use this feature if you intend to export changes back to CVS again later with -'git cvsexportcommit'. +`git cvsexportcommit`. -R:: Generate a `$GIT_DIR/cvs-revisions` file containing a mapping from CVS diff --git a/Documentation/git-cvsserver.txt b/Documentation/git-cvsserver.txt index c6a926d8d2..bf53d16a7f 100644 --- a/Documentation/git-cvsserver.txt +++ b/Documentation/git-cvsserver.txt @@ -17,12 +17,12 @@ export CVS_SERVER="git cvsserver" pserver (/etc/inetd.conf): [verse] -cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver git-cvsserver pserver +cvspserver stream tcp nowait nobody /usr/bin/git-cvsserver `git-cvsserver` pserver Usage: [verse] -'git-cvsserver' [<options>] [pserver|server] [<directory> ...] +`git-cvsserver` [<options>] [pserver|server] [<directory> ...] OPTIONS ------- @@ -74,7 +74,7 @@ LIMITATIONS CVS clients cannot tag, branch or perform Git merges. -'git-cvsserver' maps Git branches to CVS modules. This is very different +`git-cvsserver` maps Git branches to CVS modules. This is very different from what most CVS users would expect since in CVS modules usually represent one or more directories. @@ -132,7 +132,7 @@ Then provide your password via the pserver method, for example: ------ No special setup is needed for SSH access, other than having Git tools in the PATH. If you have clients that do not accept the CVS_SERVER -environment variable, you can rename 'git-cvsserver' to `cvs`. +environment variable, you can rename `git-cvsserver` to `cvs`. Note: Newer CVS versions (>= 1.12.11) also support specifying CVS_SERVER directly in CVSROOT like @@ -142,9 +142,9 @@ cvs -d ":ext;CVS_SERVER=git cvsserver:user@server/path/repo.git" co <HEAD_name> ------ This has the advantage that it will be saved in your 'CVS/Root' files and you don't need to worry about always setting the correct environment -variable. SSH users restricted to 'git-shell' don't need to override the default -with CVS_SERVER (and shouldn't) as 'git-shell' understands `cvs` to mean -'git-cvsserver' and pretends that the other end runs the real 'cvs' better. +variable. SSH users restricted to `git-shell` don't need to override the default +with CVS_SERVER (and shouldn't) as `git-shell` understands `cvs` to mean +`git-cvsserver` and pretends that the other end runs the real 'cvs' better. -- 2. For each repo that you want accessible from CVS you need to edit config in the repo and add the following section. @@ -157,7 +157,7 @@ with CVS_SERVER (and shouldn't) as 'git-shell' understands `cvs` to mean logFile=/path/to/logfile ------ -Note: you need to ensure each user that is going to invoke 'git-cvsserver' has +Note: you need to ensure each user that is going to invoke `git-cvsserver` has write access to the log file and to the database (see <<dbbackend,Database Backend>>. If you want to offer write access over SSH, the users of course also need write access to the Git repository itself. @@ -182,7 +182,7 @@ allowing access over SSH. automatically saving it in your 'CVS/Root' files, then you need to set them explicitly in your environment. CVSROOT should be set as per normal, but the directory should point at the appropriate Git repo. As above, for SSH clients - _not_ restricted to 'git-shell', CVS_SERVER should be set to 'git-cvsserver'. + _not_ restricted to `git-shell`, CVS_SERVER should be set to `git-cvsserver`. + -- ------ @@ -210,32 +210,32 @@ allowing access over SSH. DATABASE BACKEND ---------------- -'git-cvsserver' uses one database per Git head (i.e. CVS module) to +`git-cvsserver` uses one database per Git head (i.e. CVS module) to store information about the repository to maintain consistent CVS revision numbers. The database needs to be updated (i.e. written to) after every commit. If the commit is done directly by using `git` (as opposed to -using 'git-cvsserver') the update will need to happen on the -next repository access by 'git-cvsserver', independent of +using `git-cvsserver`) the update will need to happen on the +next repository access by `git-cvsserver`, independent of access method and requested operation. That means that even if you offer only read access (e.g. by using -the pserver method), 'git-cvsserver' should have write access to +the pserver method), `git-cvsserver` should have write access to the database to work reliably (otherwise you need to make sure -that the database is up to date any time 'git-cvsserver' is executed). +that the database is up to date any time `git-cvsserver` is executed). By default it uses SQLite databases in the Git directory, named `gitcvs.<module_name>.sqlite`. Note that the SQLite backend creates temporary files in the same directory as the database file on write so it might not be enough to grant the users using -'git-cvsserver' write access to the database file without granting +`git-cvsserver` write access to the database file without granting them write access to the directory, too. The database cannot be reliably regenerated in a consistent form after the branch it is tracking has changed. -Example: For merged branches, 'git-cvsserver' only tracks -one branch of development, and after a 'git merge' an +Example: For merged branches, `git-cvsserver` only tracks +one branch of development, and after a `git merge` an incrementally updated database may track a different branch than a database regenerated from scratch, causing inconsistent CVS revision numbers. `git-cvsserver` has no way of knowing which @@ -250,7 +250,7 @@ configuration variables: Configuring database backend ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -'git-cvsserver' uses the Perl DBI module. Please also read +`git-cvsserver` uses the Perl DBI module. Please also read its documentation if changing these variables, especially about `DBI->connect()`. @@ -302,7 +302,7 @@ In `dbDriver` and `dbUser` you can use the following variables: %a:: access method (one of "ext" or "pserver") %u:: - Name of the user running 'git-cvsserver'. + Name of the user running `git-cvsserver`. If no name can be determined, the numeric uid is used. @@ -310,13 +310,13 @@ ENVIRONMENT ----------- These variables obviate the need for command-line options in some -circumstances, allowing easier restricted usage through git-shell. +circumstances, allowing easier restricted usage through `git-shell`. 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 -git-cvsserver, as described above. +`git-cvsserver`, as described above. When these environment variables are set, the corresponding command-line arguments may not be used. @@ -343,8 +343,8 @@ you will definitely want to have SSH keys setup. Alternatively, you can just use the non-standard extssh protocol that Eclipse offer. In that case CVS_SERVER is ignored, and you will have to replace -the cvs utility on the server with 'git-cvsserver' or manipulate your `.bashrc` -so that calling 'cvs' effectively calls 'git-cvsserver'. +the cvs utility on the server with `git-cvsserver` or manipulate your `.bashrc` +so that calling 'cvs' effectively calls `git-cvsserver`. CLIENTS KNOWN TO WORK --------------------- @@ -361,12 +361,12 @@ 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 all. (Non-main-branch CVS revision numbers superficially resemble CVS -revision numbers, but they actually encode a git commit ID directly, +revision numbers, but they actually encode a `git` commit ID directly, rather than represent the number of revisions since the branch point.) Note that there are two ways to checkout a particular branch. @@ -383,9 +383,9 @@ operations against that main branch are fast. Or alternatively, -r doesn't take any extra disk space, but may be significantly slower for many operations, like cvs update. -If you want to refer to a git refspec that has characters that are +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 @@ -426,7 +426,7 @@ and `gitcvs.allBinary` to "guess". DEPENDENCIES ------------ -'git-cvsserver' depends on DBD::SQLite. +`git-cvsserver` depends on DBD::SQLite. GIT --- diff --git a/Documentation/git-daemon.txt b/Documentation/git-daemon.txt index 2794a2d0c1..e9cce4e468 100644 --- a/Documentation/git-daemon.txt +++ b/Documentation/git-daemon.txt @@ -8,7 +8,7 @@ git-daemon - A really simple server for Git repositories SYNOPSIS -------- [verse] -'git daemon' [--verbose] [--syslog] [--export-all] +`git daemon` [--verbose] [--syslog] [--export-all] [--timeout=<n>] [--init-timeout=<n>] [--max-connections=<n>] [--strict-paths] [--base-path=<path>] [--base-path-relaxed] [--user-path | --user-path=<path>] @@ -29,39 +29,39 @@ A really simple TCP Git daemon that normally listens on port "DEFAULT_GIT_PORT" aka 9418. It waits for a connection asking for a service, and will serve that service if it is enabled. -It verifies that the directory has the magic file "git-daemon-export-ok", and +It verifies that the directory has the magic file `git-daemon-export-ok`, and it will refuse to export any Git directory that hasn't explicitly been marked for export this way (unless the `--export-all` parameter is specified). If you -pass some directory paths as 'git daemon' arguments, you can further restrict +pass some directory paths as `git daemon` arguments, you can further restrict the offers to a whitelist comprising of those. By default, only `upload-pack` service is enabled, which serves -'git fetch-pack' and 'git ls-remote' clients, which are invoked -from 'git fetch', 'git pull', and 'git clone'. +`git fetch-pack` and `git ls-remote` clients, which are invoked +from `git fetch`, `git pull`, and `git clone`. This is ideally suited for read-only updates, i.e., pulling from Git repositories. -An `upload-archive` also exists to serve 'git archive'. +An `upload-archive` also exists to serve `git archive`. OPTIONS ------- --strict-paths:: Match paths exactly (i.e. don't allow "/foo/repo" when the real path is "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths. - 'git daemon' will refuse to start when this option is enabled and no + `git daemon` will refuse to start when this option is enabled and no whitelist is specified. --base-path=<path>:: Remap all the path requests as relative to the given path. - This is sort of "Git root" - if you run 'git daemon' with + 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 - 'git://example.com/hello.git', 'git daemon' will interpret the path + '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 - 'git daemon' will attempt to lookup without prefixing the base path. + `git daemon` will attempt to lookup without prefixing the base path. This is useful for switching to `--base-path` usage, while still allowing the old paths. @@ -78,7 +78,7 @@ OPTIONS --export-all:: Allow pulling from all directories that look like Git repositories (have the 'objects' and 'refs' subdirectories), even if they - do not have the 'git-daemon-export-ok' file. + do not have the `git-daemon-export-ok` file. --inetd:: Have the server run as an inetd service. Implies `--syslog` (may be @@ -170,10 +170,10 @@ otherwise `stderr`. + Giving these options is an error when used with `--inetd`; use the facility of inet daemon to achieve the same before spawning -'git daemon' if needed. +`git daemon` if needed. + Like many programs that switch user id, the daemon does not reset -environment variables such as `$HOME` when it runs git programs, +environment variables such as `$HOME` when it runs `git` programs, e.g. `upload-pack` and `receive-pack`. When using this option, you may also want to set and export `HOME` to point at the home directory of `<user>` before starting the daemon, and make sure any @@ -194,7 +194,7 @@ Git configuration files in that directory are readable by `<user>`. may be overridden. --[no-]informative-errors:: - When informative errors are turned on, git-daemon will report + When informative errors are turned on, `git-daemon` will report more verbose errors to the client, differentiating conditions like "no such repository" from "repository not exported". This is more convenient for clients, but may leak information about @@ -227,24 +227,24 @@ SERVICES These services can be globally enabled/disabled using the command-line options of this command. If finer-grained -control is desired (e.g. to allow 'git archive' to be run +control is desired (e.g. to allow `git archive` to be run against only in a few selected repositories the daemon serves), the per-repository configuration file can be used to enable or disable them. upload-pack:: - This serves 'git fetch-pack' and 'git ls-remote' + This serves `git fetch-pack` and `git ls-remote` clients. It is enabled by default, but a repository can disable it by setting `daemon.uploadpack` configuration item to `false`. upload-archive:: - This serves 'git archive --remote'. It is disabled by + This serves `git archive --remote`. It is disabled by default, but a repository can enable it by setting `daemon.uploadarch` configuration item to `true`. receive-pack:: - This serves 'git send-pack' clients, allowing anonymous + This serves `git send-pack` clients, allowing anonymous push. It is disabled by default, as there is _no_ authentication in the protocol (in other words, anybody can push anything into the repository, including removal @@ -262,8 +262,8 @@ $ grep 9418 /etc/services git 9418/tcp # Git Version Control System ------------ -'git daemon' as inetd server:: - To set up 'git daemon' as an inetd service that handles any +`git daemon` as inetd server:: + To set up `git daemon` as an inetd service that handles any repository under the whitelisted set of directories, /pub/foo and /pub/bar, place an entry like the following into /etc/inetd all on one line: @@ -275,8 +275,8 @@ git 9418/tcp # Git Version Control System ------------------------------------------------ -'git daemon' as inetd server for virtual hosts:: - To set up 'git daemon' as an inetd service that handles +`git daemon` as inetd server for virtual hosts:: + To set up `git daemon` as an inetd service that handles repositories for different virtual hosts, `www.example.com` and `www.example.org`, place an entry like the following into `/etc/inetd` all on one line: @@ -298,8 +298,8 @@ clients, a symlink from `/software` into the appropriate default repository could be made as well. -'git daemon' as regular daemon for virtual hosts:: - To set up 'git daemon' as a regular, non-inetd service that +`git daemon` as regular daemon for virtual hosts:: + To set up `git daemon` as a regular, non-inetd service that handles repositories for multiple virtual hosts based on their IP addresses, start the daemon like this: + @@ -316,7 +316,7 @@ Repositories can still be accessed by hostname though, assuming they correspond to these IP addresses. selectively enable/disable services per repository:: - To enable 'git archive --remote' and disable 'git fetch' against + To enable `git archive --remote` and disable `git fetch` against a repository, have the following in the configuration file in the repository (that is the file 'config' next to `HEAD`, 'refs' and 'objects'). @@ -330,7 +330,7 @@ selectively enable/disable services per repository:: ENVIRONMENT ----------- -'git daemon' will set REMOTE_ADDR to the IP address of the client +`git daemon` will set REMOTE_ADDR to the IP address of the client that connected to it, if the IP address is available. REMOTE_ADDR will be available in the environment of hooks called when services are performed. diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 7d2649c477..6cfb444444 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -8,9 +8,9 @@ git-describe - Give an object a human readable name based on an available ref SYNOPSIS -------- [verse] -'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...] -'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] -'git describe' <blob> +`git describe` [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...] +`git describe` [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] +`git describe` <blob> DESCRIPTION ----------- @@ -20,7 +20,7 @@ shown. Otherwise, it suffixes the tag name with the number of additional commits on top of the tagged object and the 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. +identify the commit to other `git` commands. By default (without `--all` or `--tags`) `git describe` only shows annotated tags. For more information about creating annotated tags @@ -40,8 +40,8 @@ OPTIONS --dirty[=<mark>]:: --broken[=<mark>]:: Describe the state of the working tree. When the working - tree matches `HEAD`, the output is the same as "git describe - HEAD". If the working tree has local modification "-dirty" + tree matches `HEAD`, the output is the same as `git describe + HEAD`. If the working tree has local modification "-dirty" is appended to it. If a repository is corrupt and Git cannot determine if there is local modification, Git will error out, unless `--broken' is given, which appends @@ -138,14 +138,14 @@ an abbreviated object name for the commit itself ("2414721") at the end. The number of additional commits is the number -of commits which would be displayed by "git log v1.0.4..parent". +of commits which would be displayed by `git log v1.0.4..parent`. The hash suffix is "-g" + unambiguous abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). -The "g" prefix stands for "git" and is used to allow describing the version of +The "g" prefix stands for `git` and is used to allow describing the version of a software depending on the SCM the software is managed with. This is useful in an environment where people may use different SCMs. -Doing a 'git describe' on a tag-name will just show the tag name: +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 @@ -175,13 +175,13 @@ be sufficient to disambiguate these commits. SEARCH STRATEGY --------------- -For each commit-ish supplied, 'git describe' will first look for +For each commit-ish supplied, `git describe` will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match is found, its name will be output and searching will stop. -If an exact match was not found, 'git describe' will walk back +If an exact match was not found, `git describe` will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an abbreviation of the input commit-ish's SHA-1. If `--first-parent` was diff --git a/Documentation/git-diff-files.txt b/Documentation/git-diff-files.txt index 906774f0f7..b0fb276b99 100644 --- a/Documentation/git-diff-files.txt +++ b/Documentation/git-diff-files.txt @@ -9,14 +9,14 @@ git-diff-files - Compares files in the working tree and the index SYNOPSIS -------- [verse] -'git diff-files' [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...] +`git diff-files` [-q] [-0|-1|-2|-3|-c|--cc] [<common diff options>] [<path>...] DESCRIPTION ----------- Compares the files in the working tree and the index. When paths are specified, compares only those named paths. Otherwise all entries in the index are compared. The output format is the -same as for 'git diff-index' and 'git diff-tree'. +same as for `git diff-index` and `git diff-tree`. OPTIONS ------- diff --git a/Documentation/git-diff-index.txt b/Documentation/git-diff-index.txt index 10e79a29aa..87db234e77 100644 --- a/Documentation/git-diff-index.txt +++ b/Documentation/git-diff-index.txt @@ -9,7 +9,7 @@ git-diff-index - Compare a tree to the working tree or index SYNOPSIS -------- [verse] -'git diff-index' [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...] +`git diff-index` [-m] [--cached] [--merge-base] [<common diff options>] <tree-ish> [<path>...] DESCRIPTION ----------- @@ -37,7 +37,7 @@ include::diff-options.txt[] -m:: By default, files recorded in the index but not checked out are reported as deleted. This flag makes - 'git diff-index' say that all non-checked-out files are up + `git diff-index` say that all non-checked-out files are up to date. include::diff-format.txt[] @@ -54,7 +54,7 @@ CACHED MODE If `--cached` is specified, it allows you to ask: show me the differences between `HEAD` and the current index - contents (the ones I'd write using 'git write-tree') + contents (the ones I'd write using `git write-tree`) For example, let's say that you have worked on your working directory, updated some files in the index and are ready to commit. You want to see exactly @@ -66,7 +66,7 @@ object and compare it that way, and to do that, you just do Example: let's say I had renamed `commit.c` to `git-commit.c`, and I had done an `update-index` to make that effective in the index file. `git diff-files` wouldn't show anything at all, since the index file -matches my working directory. But doing a 'git diff-index' does: +matches my working directory. But doing a `git diff-index` does: torvalds@ppc970:~/git> git diff-index --cached HEAD -100644 blob 4161aecc6700a2eb579e842af0b7f22b98443f74 commit.c @@ -75,7 +75,7 @@ matches my working directory. But doing a 'git diff-index' does: You can see easily that the above is a rename. In fact, `git diff-index --cached` *should* always be entirely equivalent to -actually doing a 'git write-tree' and comparing that. Except this one is much +actually doing a `git write-tree` and comparing that. Except this one is much nicer for the case where you just want to check where you are. So doing a `git diff-index --cached` is basically very useful when you are @@ -86,20 +86,20 @@ NON-CACHED MODE --------------- The "non-cached" mode takes a different approach, and is potentially the more useful of the two in that what it does can't be emulated with -a 'git write-tree' + 'git diff-tree'. Thus that's the default mode. +a `git write-tree` + `git diff-tree`. Thus that's the default mode. The non-cached version asks the question: show me the differences between `HEAD` and the currently checked out tree - index contents _and_ files that aren't up to date which is obviously a very useful question too, since that tells you what -you *could* commit. Again, the output matches the 'git diff-tree -r' +you *could* commit. Again, the output matches the `git diff-tree -r` output to a tee, but with a twist. The twist is that if some file doesn't match the index, we don't have a backing store thing for it, and we use the magic "all-zero" sha1 to show that. So let's say that you have edited `kernel/sched.c`, but -have not actually done a 'git update-index' on it yet - there is no +have not actually done a `git update-index` on it yet - there is no "object" associated with the new state, and you get: torvalds@ppc970:~/v2.6/linux> git diff-index --abbrev HEAD @@ -110,11 +110,11 @@ not up to date and may contain new stuff. The all-zero sha1 means that to get the real diff, you need to look at the object in the working directory directly rather than do an object-to-object diff. -NOTE: As with other commands of this type, 'git diff-index' does not +NOTE: As with other commands of this type, `git diff-index` does not actually look at the contents of the file at all. So maybe `kernel/sched.c` hasn't actually changed, and it's just that you touched it. In either case, it's a note that you need to -'git update-index' it to make the index be in sync. +`git update-index` it to make the index be in sync. NOTE: You can have a mixture of files show up as "has been updated" and "is still dirty in the working directory" together. You can always diff --git a/Documentation/git-diff-tree.txt b/Documentation/git-diff-tree.txt index b9225cd824..56354886a4 100644 --- a/Documentation/git-diff-tree.txt +++ b/Documentation/git-diff-tree.txt @@ -9,7 +9,7 @@ git-diff-tree - Compares the content and mode of blobs found via two tree object SYNOPSIS -------- [verse] -'git diff-tree' [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] +`git diff-tree` [--stdin] [-m] [-s] [-v] [--no-commit-id] [--pretty] [-t] [-r] [-c | --cc] [--combined-all-paths] [--root] [--merge-base] [<common diff options>] <tree-ish> [<tree-ish>] [<path>...] @@ -20,7 +20,7 @@ Compares the content and mode of the blobs found via two tree objects. If there is only one <tree-ish> given, the commit is compared with its parents (see `--stdin` below). -Note that 'git diff-tree' can use the tree encapsulated in a commit object. +Note that `git diff-tree` can use the tree encapsulated in a commit object. OPTIONS ------- @@ -69,25 +69,25 @@ The following flags further affect the behavior when comparing commits (but not trees). -m:: - By default, 'git diff-tree --stdin' does not show + By default, `git diff-tree --stdin` does not show differences for merge commits. With this flag, it shows differences to that commit from all of its parents. See also `-c`. -s:: - By default, 'git diff-tree --stdin' shows differences, + By default, `git diff-tree --stdin` shows differences, either in machine-readable form (without `-p`) or in patch form (with `-p`). This output can be suppressed. It is only useful with `-v` flag. -v:: - This flag causes 'git diff-tree --stdin' to also show + This flag causes `git diff-tree --stdin` to also show the commit message before the differences. include::pretty-options.txt[] --no-commit-id:: - 'git diff-tree' outputs a line with the commit ID when + `git diff-tree` outputs a line with the commit ID when applicable. This flag suppressed the commit ID output. -c:: diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt index 33a47958bc..7779631421 100644 --- a/Documentation/git-diff.txt +++ b/Documentation/git-diff.txt @@ -9,12 +9,12 @@ git-diff - Show changes between commits, commit and working tree, etc SYNOPSIS -------- [verse] -'git diff' [<options>] [<commit>] [--] [<path>...] -'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...] -'git diff' [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...] -'git diff' [<options>] <commit>...<commit> [--] [<path>...] -'git diff' [<options>] <blob> <blob> -'git diff' [<options>] --no-index [--] <path> <path> +`git diff` [<options>] [<commit>] [--] [<path>...] +`git diff` [<options>] --cached [--merge-base] [<commit>] [--] [<path>...] +`git diff` [<options>] [--merge-base] <commit> [<commit>...] <commit> [--] [<path>...] +`git diff` [<options>] <commit>...<commit> [--] [<path>...] +`git diff` [<options>] <blob> <blob> +`git diff` [<options>] --no-index [--] <path> <path> DESCRIPTION ----------- @@ -23,7 +23,7 @@ between the index and a tree, changes between two trees, changes resulting from a merge, changes between two blob objects, or changes between two files on disk. -'git diff' [<options>] [--] [<path>...]:: +`git diff` [<options>] [--] [<path>...]:: This form is to view the changes you made relative to the index (staging area for the next commit). In other @@ -31,7 +31,7 @@ files on disk. further add to the index but you still haven't. You can stage these changes by using linkgit:git-add[1]. -'git diff' [<options>] --no-index [--] <path> <path>:: +`git diff` [<options>] --no-index [--] <path> <path>:: This form is to compare the given two paths on the filesystem. You can omit the `--no-index` option when @@ -40,7 +40,7 @@ files on disk. or when running the command outside a working tree controlled by Git. This form implies `--exit-code`. -'git diff' [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]:: +`git diff` [<options>] --cached [--merge-base] [<commit>] [--] [<path>...]:: This form is to view the changes you staged for the next commit relative to the named <commit>. Typically you @@ -54,7 +54,7 @@ If `--merge-base` is given, instead of using <commit>, use the merge base of <commit> and `HEAD`. `git diff --merge-base A` is equivalent to `git diff $(git merge-base A HEAD)`. -'git diff' [<options>] <commit> [--] [<path>...]:: +`git diff` [<options>] <commit> [--] [<path>...]:: This form is to view the changes you have in your working tree relative to the named <commit>. You can @@ -62,7 +62,7 @@ of <commit> and `HEAD`. `git diff --merge-base A` is equivalent to branch name to compare with the tip of a different branch. -'git diff' [<options>] [--merge-base] <commit> <commit> [--] [<path>...]:: +`git diff` [<options>] [--merge-base] <commit> <commit> [--] [<path>...]:: This is to view the changes between two arbitrary <commit>. @@ -71,7 +71,7 @@ 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`. -'git diff' [<options>] <commit> <commit>... <commit> [--] [<path>...]:: +`git diff` [<options>] <commit> <commit>... <commit> [--] [<path>...]:: This form is to view the results of a merge commit. The first listed <commit> must be the merge itself; the remaining two or @@ -80,14 +80,14 @@ If `--merge-base` is given, use the merge base of the two commits for the For instance, if `master` names a merge commit, `git diff master master^@` gives the same combined diff as `git show master`. -'git diff' [<options>] <commit>..<commit> [--] [<path>...]:: +`git diff` [<options>] <commit>..<commit> [--] [<path>...]:: This is synonymous to the earlier form (without the `..`) for viewing the changes between two arbitrary <commit>. If <commit> on one side is omitted, it will have the same effect as using `HEAD` instead. -'git diff' [<options>] <commit>\...<commit> [--] [<path>...]:: +`git diff` [<options>] <commit>\...<commit> [--] [<path>...]:: This form is to view the changes on the branch containing and up to the second <commit>, starting at a common ancestor @@ -107,7 +107,7 @@ and the range notations (`<commit>..<commit>` and `<commit>...<commit>`) do not mean a range as defined in the "SPECIFYING RANGES" section in linkgit:gitrevisions[7]. -'git diff' [<options>] <blob> <blob>:: +`git diff` [<options>] <blob> <blob>:: This form is to view the differences between the raw contents of two blob objects. diff --git a/Documentation/git-difftool.txt b/Documentation/git-difftool.txt index 143b0c49d7..b646654941 100644 --- a/Documentation/git-difftool.txt +++ b/Documentation/git-difftool.txt @@ -8,13 +8,13 @@ git-difftool - Show changes using common diff tools SYNOPSIS -------- [verse] -'git difftool' [<options>] [<commit> [<commit>]] [--] [<path>...] +`git difftool` [<options>] [<commit> [<commit>]] [--] [<path>...] DESCRIPTION ----------- -'git difftool' is a Git command that allows you to compare and edit files -between revisions using common diff tools. 'git difftool' is a frontend -to 'git diff' and accepts the same options and arguments. See +`git difftool` is a Git command that allows you to compare and edit files +between revisions using common diff tools. `git difftool` is a frontend +to `git diff` and accepts the same options and arguments. See linkgit:git-diff[1]. OPTIONS @@ -48,23 +48,23 @@ OPTIONS emerge, kompare, meld, and vimdiff. Run `git difftool --tool-help` for the list of valid <tool> settings. + -If a diff tool is not specified, 'git difftool' +If a diff tool is not specified, `git difftool` will use the configuration variable `diff.tool`. If the -configuration variable `diff.tool` is not set, 'git difftool' +configuration variable `diff.tool` is not set, `git difftool` will pick a suitable default. + You can explicitly provide a full path to the tool by setting the configuration variable `difftool.<tool>.path`. For example, you can configure the absolute path to kdiff3 by setting -`difftool.kdiff3.path`. Otherwise, 'git difftool' assumes the +`difftool.kdiff3.path`. Otherwise, `git difftool` assumes the tool is available in PATH. + Instead of running one of the known diff tools, -'git difftool' can be customized to run an alternative program +`git difftool` can be customized to run an alternative program by specifying the command line to invoke in a configuration variable `difftool.<tool>.cmd`. + -When 'git difftool' is invoked with this tool (either through the +When `git difftool` is invoked with this tool (either through the `-t` or `--tool` option or the `diff.tool` configuration variable) the configured command line will be invoked with the following variables available: `$LOCAL` is set to the name of the temporary @@ -78,24 +78,24 @@ with custom merge tool commands and has the same value as `$MERGED`. Print a list of diff tools that may be used with `--tool`. --[no-]symlinks:: - 'git difftool''s default behavior is create symlinks to the + `git difftool`'s default behavior is create symlinks to the working tree when run in `--dir-diff` mode and the right-hand side of the comparison yields the same content as the file in the working tree. + -Specifying `--no-symlinks` instructs 'git difftool' to create copies +Specifying `--no-symlinks` instructs `git difftool` to create copies instead. `--no-symlinks` is the default on Windows. -x <command>:: --extcmd=<command>:: Specify a custom command for viewing diffs. - 'git-difftool' ignores the configured defaults and runs + `git-difftool` ignores the configured defaults and runs `$command $LOCAL $REMOTE` when this option is specified. Additionally, `$BASE` is set in the environment. -g:: --[no-]gui:: - When 'git-difftool' is invoked with the `-g` or `--gui` option + When `git-difftool` is invoked with the `-g` or `--gui` option the default diff tool will be read from the configured `diff.guitool` variable instead of `diff.tool`. The `--no-gui` option can be used to override this setting. If `diff.guitool` @@ -103,19 +103,19 @@ instead. `--no-symlinks` is the default on Windows. `diff.tool`, `merge.tool` until a tool is found. --[no-]trust-exit-code:: - 'git-difftool' invokes a diff tool individually on each file. + `git-difftool` invokes a diff tool individually on each file. Errors reported by the diff tool are ignored by default. - Use `--trust-exit-code` to make 'git-difftool' exit when an + Use `--trust-exit-code` to make `git-difftool` exit when an invoked diff tool returns a non-zero exit code. + -'git-difftool' will forward the exit code of the invoked tool when +`git-difftool` will forward the exit code of the invoked tool when `--trust-exit-code` is used. See linkgit:git-diff[1] for the full list of supported options. CONFIG VARIABLES ---------------- -'git difftool' falls back to 'git mergetool' config variables when the +`git difftool` falls back to `git mergetool` config variables when the difftool equivalents have not been defined. diff.tool:: diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt index 3a6a77abac..24b10d4ad1 100644 --- a/Documentation/git-fast-export.txt +++ b/Documentation/git-fast-export.txt @@ -9,23 +9,23 @@ git-fast-export - Git data exporter SYNOPSIS -------- [verse] -'git fast-export [<options>]' | 'git fast-import' +`git fast-export [<options>]` | `git fast-import` DESCRIPTION ----------- This program dumps the given revisions in a form suitable to be piped -into 'git fast-import'. +into `git fast-import`. You can use it as a human-readable bundle replacement (see linkgit:git-bundle[1]), or as a format that can be edited before being -fed to 'git fast-import' in order to do history rewrites (an ability -relied on by tools like 'git filter-repo'). +fed to `git fast-import` in order to do history rewrites (an ability +relied on by tools like `git filter-repo`). OPTIONS ------- --progress=<n>:: Insert 'progress' statements every <n> objects, to be shown by - 'git fast-import' during import. + `git fast-import` during import. --signed-tags=(verbatim|warn|warn-strip|strip|abort):: Specify how to handle signed tags. Since any transformation @@ -139,7 +139,7 @@ by keeping the marks the same across runs. --show-original-ids:: Add an extra directive to the output for commits and blobs, `original-oid <SHA1SUM>`. While such directives will likely be - ignored by importers such as git-fast-import, it may be useful + ignored by importers such as `git-fast-import`, it may be useful for intermediary filters (e.g. for rewriting commit messages which refer to older commits, or for stripping blobs by id). @@ -155,8 +155,8 @@ by keeping the marks the same across runs. be specified. [<git-rev-list-args>...]:: - A list of arguments, acceptable to 'git rev-parse' and - 'git rev-list', that specifies the specific objects and references + A list of arguments, acceptable to `git rev-parse` and + `git rev-list`, that specifies the specific objects and references 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 @@ -191,14 +191,14 @@ referenced by that revision range contains the string ANONYMIZING ----------- -If the `--anonymize` option is given, git will attempt to remove all +If the `--anonymize` option is given, `git` will attempt to remove all identifying information from the repository while still retaining enough of the original tree and history patterns to reproduce some bugs. The -goal is that a git bug which is found on a private repository will +goal is that a `git` bug which is found on a private repository will persist in the anonymized repository, and the latter can be shared with -git developers to help solve the bug. +`git` developers to help solve the bug. -With this option, git will replace all refnames, paths, blob contents, +With this option, `git` will replace all refnames, paths, blob contents, commit and tag messages, names, and email addresses in the output with anonymized data. Two instances of the same string will be replaced equivalently (e.g., two commits with the same author will have the same @@ -210,7 +210,7 @@ the tree is retained (e.g., if you have a root tree with 10 files and 3 trees, so will the output), but their names and the contents of the files will be replaced. -If you think you have found a git bug, you can start by exporting an +If you think you have found a `git` bug, you can start by exporting an anonymized stream of the whole repository: --------------------------------------------------- @@ -271,7 +271,7 @@ final pathname would be `publicdir/bar.c`. LIMITATIONS ----------- -Since 'git fast-import' cannot tag trees, you will not be +Since `git fast-import` cannot tag trees, you will not be able to export the linux.git repository completely, as it contains a tag referencing a tree instead of a commit. diff --git a/Documentation/git-fast-import.txt b/Documentation/git-fast-import.txt index ff67238633..eeac242732 100644 --- a/Documentation/git-fast-import.txt +++ b/Documentation/git-fast-import.txt @@ -9,14 +9,14 @@ git-fast-import - Backend for fast Git data importers SYNOPSIS -------- [verse] -frontend | 'git fast-import' [<options>] +frontend | `git fast-import` [<options>] DESCRIPTION ----------- This program is usually not what the end user wants to run directly. Most end users want to use one of the existing frontend programs, which parses a specific type of foreign source and feeds the contents -stored there to 'git fast-import'. +stored there to `git fast-import`. fast-import reads a mixed command/data stream from standard input and writes one or more packfiles directly into the current repository. @@ -25,7 +25,7 @@ updated branch and tag refs, fully updating the current repository with the newly imported data. The fast-import backend itself can import into an empty repository (one that -has already been initialized by 'git init') or incrementally +has already been initialized by `git init`) or incrementally update an existing populated repository. Whether or not incremental imports are supported from a particular foreign source depends on the frontend program in use. @@ -115,7 +115,7 @@ Locations of Marks Files 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 + In `git-fast-import` this means that the paths are relative to the .git/info/fast-import directory. However, other importers may use a different location. + @@ -166,7 +166,7 @@ Performance and Compression Tuning This information may be useful after importing projects whose total object set exceeds the 4 GiB packfile limit, as these commits can be used as edge points during calls - to 'git pack-objects'. + to `git pack-objects`. --max-pack-size=<n>:: Maximum size of each output packfile. @@ -203,9 +203,9 @@ an ideal situation, given that most conversion tools are throw-away PARALLEL OPERATION ------------------ -Like 'git push' or 'git fetch', imports handled by fast-import are safe to +Like `git push` or `git fetch`, imports handled by fast-import are safe to run alongside parallel `git repack -a -d` or `git gc` invocations, -or any other Git operation (including 'git prune', as loose objects +or any other Git operation (including `git prune`, as loose objects are never used by fast-import). fast-import does not lock the branch or tag refs it is actively importing. @@ -307,7 +307,7 @@ and some sanity checks on the numeric values may also be performed. + An example value is ``Tue Feb 6 11:22:18 2007 -0500''. The Git parser is accurate, but a little on the lenient side. It is the -same parser used by 'git am' when applying patches +same parser used by `git am` when applying patches received from email. + Some malformed strings may be accepted as valid dates. In some of @@ -343,7 +343,7 @@ time zone. This particular format is supplied as it's short to implement and may be useful to a process that wants to create a new commit right now, without needing to use a working directory or -'git update-index'. +`git update-index`. + If separate `author` and `committer` commands are used in a `commit` the timestamps may not match, as the system clock will be polled @@ -509,7 +509,7 @@ their syntax. ^^^^^^^^^^ The optional `encoding` command indicates the encoding of the commit message. Most commits are UTF-8 and the encoding is omitted, but this -allows importing commit messages into git without first reencoding them. +allows importing commit messages into `git` without first reencoding them. `from` ^^^^^^ @@ -859,7 +859,7 @@ recommended, as the frontend does not (easily) have access to the complete set of bytes which normally goes into such a signature. If signing is required, create lightweight tags from within fast-import with `reset`, then create the annotated versions of those tags offline -with the standard 'git tag' process. +with the standard `git tag` process. `reset` ~~~~~~~ @@ -1120,7 +1120,7 @@ The <dataref> represents the blob, tree, or commit object at <path> and can be used in later 'get-mark', 'cat-blob', 'filemodify', or 'ls' commands. -If there is no file or subtree at that path, 'git fast-import' will +If there is no file or subtree at that path, `git fast-import` will instead report ==== @@ -1183,14 +1183,14 @@ done:: abruptly at a convenient point in the stream can go undetected. This may occur, for example, if an import front end dies in mid-operation without emitting SIGTERM - or SIGKILL at its subordinate git fast-import instance. + or SIGKILL at its subordinate `git fast-import` instance. `option` ~~~~~~~~ -Processes the specified option so that git fast-import behaves in a +Processes the specified option so that `git fast-import` behaves in a way that suits the frontend's needs. Note that options specified by the frontend are overridden by any -options the user may specify to git fast-import itself. +options the user may specify to `git fast-import` itself. .... 'option' SP <option> LF @@ -1396,7 +1396,7 @@ is not `refs/heads/TAG_FIXUP`). When committing fixups, consider using `merge` to connect the commit(s) which are supplying file revisions to the fixup branch. -Doing so will allow tools such as 'git blame' to track +Doing so will allow tools such as `git blame` to track through the real commit history and properly annotate the source files. @@ -1425,7 +1425,7 @@ Repacking Historical Data ~~~~~~~~~~~~~~~~~~~~~~~~~ If you are repacking very old imported data (e.g. older than the last year), consider expending some extra CPU time and supplying -`--window=50` (or higher) when you run 'git repack'. +`--window=50` (or higher) when you run `git repack`. This will take longer, but will also produce a smaller packfile. You only need to expend the effort once, and everyone using your project will benefit from the smaller repository. @@ -1558,7 +1558,7 @@ memory footprint (less than 2.7 MiB per active branch). SIGNALS ------- -Sending *SIGUSR1* to the 'git fast-import' process ends the current +Sending *SIGUSR1* to the `git fast-import` process ends the current packfile early, simulating a `checkpoint` command. The impatient operator can use this facility to peek at the objects and refs from an import in progress, at the cost of some added running time and worse diff --git a/Documentation/git-fetch-pack.txt b/Documentation/git-fetch-pack.txt index 1f48f89e3e..eaca893ac8 100644 --- a/Documentation/git-fetch-pack.txt +++ b/Documentation/git-fetch-pack.txt @@ -9,21 +9,21 @@ git-fetch-pack - Receive missing objects from another repository SYNOPSIS -------- [verse] -'git fetch-pack' [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] +`git fetch-pack` [--all] [--quiet|-q] [--keep|-k] [--thin] [--include-tag] [--upload-pack=<git-upload-pack>] [--depth=<n>] [--no-progress] [-v] <repository> [<refs>...] DESCRIPTION ----------- -Usually you would want to use 'git fetch', which is a +Usually you would want to use `git fetch`, which is a higher level wrapper of this command, instead. -Invokes 'git-upload-pack' on a possibly remote repository +Invokes `git-upload-pack` on a possibly remote repository and asks it to send objects missing from this repository, to update the named heads. The list of commits available locally is found out by scanning the local refs/ hierarchy and sent to -'git-upload-pack' running on the other end. +`git-upload-pack` running on the other end. This command degenerates to download everything to complete the asked refs from the remote side when the local side does not @@ -47,12 +47,12 @@ be in a separate packet, and the list must end with a flush packet. -q:: --quiet:: - Pass `-q` flag to 'git unpack-objects'; this makes the + Pass `-q` flag to `git unpack-objects`; this makes the cloning process less verbose. -k:: --keep:: - Do not invoke 'git unpack-objects' on received data, but + Do not invoke `git unpack-objects` on received data, but create a single packfile out of it instead, and store it in the object database. If provided twice then the pack is locked against repacking. @@ -68,11 +68,11 @@ be in a separate packet, and the list must end with a flush packet. otherwise determine the tags this option made available. --upload-pack=<git-upload-pack>:: - Use this to specify the path to 'git-upload-pack' on the + Use this to specify the path to `git-upload-pack` on the remote side, if is not found on your $PATH. Installations of sshd ignores the user's environment setup scripts for login shells (e.g. .bash_profile) and - your privately installed git may not be found on the system + your privately installed `git` may not be found on the system default $PATH. Another workaround suggested is to set up your $PATH in ".bashrc", but this flag is for people who do not want to pay the overhead for non-interactive @@ -84,7 +84,7 @@ be in a separate packet, and the list must end with a flush packet. --depth=<n>:: Limit fetching to ancestor-chains not longer than n. - 'git-upload-pack' treats the special depth 2147483647 as + `git-upload-pack` treats the special depth 2147483647 as infinite even if there is an ancestor-chain that long. --shallow-since=<date>:: diff --git a/Documentation/git-fetch.txt b/Documentation/git-fetch.txt index 6c3f41399f..b0b5d06aad 100644 --- a/Documentation/git-fetch.txt +++ b/Documentation/git-fetch.txt @@ -9,10 +9,10 @@ git-fetch - Download objects and refs from another repository SYNOPSIS -------- [verse] -'git fetch' [<options>] [<repository> [<refspec>...]] -'git fetch' [<options>] <group> -'git fetch' --multiple [<options>] [(<repository> | <group>)...] -'git fetch' --all [<options>] +`git fetch` [<options>] [<repository> [<refspec>...]] +`git fetch` [<options>] <group> +`git fetch` --multiple [<options>] [(<repository> | <group>)...] +`git fetch` --all [<options>] DESCRIPTION @@ -30,7 +30,7 @@ configuring `remote.<name>.tagOpt`. By using a refspec that fetches tags explicitly, you can fetch tags that do not point into branches you are interested in as well. -'git fetch' can fetch from either a single named repository or URL, +`git fetch` can fetch from either a single named repository or URL, or from several repositories at once if <group> is given and there is a `remotes.<group>` entry in the configuration file. (See linkgit:git-config[1]). @@ -40,7 +40,7 @@ unless there's an upstream branch configured for the current branch. The names of refs that are fetched, together with the object names they point at, are written to `.git/FETCH_HEAD`. This information -may be used by scripts or other git commands, such as linkgit:git-pull[1]. +may be used by scripts or other `git` commands, such as linkgit:git-pull[1]. OPTIONS ------- @@ -193,7 +193,7 @@ $ git fetch <url of origin> --prune 'refs/tags/*:refs/tags/*' OUTPUT ------ -The output of "git fetch" depends on the transport method used; this +The output of `git fetch` depends on the transport method used; this section describes the output when fetching over the Git protocol (either locally or via ssh) and Smart HTTP protocol. diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt index 520d3df371..b21205d265 100644 --- a/Documentation/git-filter-branch.txt +++ b/Documentation/git-filter-branch.txt @@ -8,7 +8,7 @@ git-filter-branch - Rewrite branches SYNOPSIS -------- [verse] -'git filter-branch' [--setup <command>] [--subdirectory-filter <directory>] +`git filter-branch` [--setup <command>] [--subdirectory-filter <directory>] [--env-filter <command>] [--tree-filter <command>] [--index-filter <command>] [--parent-filter <command>] [--msg-filter <command>] [--commit-filter <command>] @@ -18,13 +18,13 @@ SYNOPSIS WARNING ------- -'git filter-branch' has a plethora of pitfalls that can produce non-obvious +`git filter-branch` has a plethora of pitfalls that can produce non-obvious manglings of the intended history rewrite (and can leave you with little time to investigate such problems since it has such abysmal performance). These safety and performance issues cannot be backward compatibly fixed and as such, its use is not recommended. Please use an alternative history filtering tool such as https://github.com/newren/git-filter-repo/[git -filter-repo]. If you still need to use 'git filter-branch', please +filter-repo]. If you still need to use `git filter-branch`, please carefully read <<SAFETY>> (and <<PERFORMANCE>>) to learn about the land mines of filter-branch, and then vigilantly avoid as many of the hazards listed there as reasonably possible. @@ -145,7 +145,7 @@ OPTIONS --commit-filter <command>:: This is the filter for performing the commit. If this filter is specified, it will be called instead of the - 'git commit-tree' command, with arguments of the form + `git commit-tree` command, with arguments of the form "<TREE_ID> [(-p <PARENT_COMMIT_ID>)...]" and the log message on stdin. The commit id is expected on stdout. + @@ -156,7 +156,7 @@ have all of them as parents. You can use the 'map' convenience function in this filter, and other convenience functions, too. For example, calling 'skip_commit "$@"' will leave out the current commit (but not its changes! If you want -that, use 'git rebase' instead). +that, use `git rebase` instead). + You can also use the `git_commit_non_empty_tree "$@"` instead of `git commit-tree "$@"` if you don't wish to keep commits with a single parent @@ -187,7 +187,7 @@ to other tags will be rewritten to point to the underlying commit. --prune-empty:: Some filters will generate empty commits that leave the tree untouched. - This option instructs git-filter-branch to remove such commits if they + This option instructs `git-filter-branch` to remove such commits if they have exactly one or zero non-pruned parents; merge commits will therefore remain intact. This option cannot be used together with `--commit-filter`, though the same effect can be achieved by using the @@ -207,7 +207,7 @@ to other tags will be rewritten to point to the underlying commit. -f:: --force:: - 'git filter-branch' refuses to start with an existing temporary + `git filter-branch` refuses to start with an existing temporary directory or when there are already refs starting with 'refs/original/', unless forced. @@ -218,10 +218,10 @@ to other tags will be rewritten to point to the underlying commit. trees. If '<branch>' does not exist it will be created. <rev-list options>...:: - Arguments for 'git rev-list'. All positive refs included by + Arguments for `git rev-list`. All positive refs included by these options are rewritten. You may also specify options such as `--all`, but you must use `--` to separate them from - the 'git filter-branch' options. Implies <<Remap_to_ancestor>>. + the `git filter-branch` options. Implies <<Remap_to_ancestor>>. [[Remap_to_ancestor]] @@ -257,7 +257,7 @@ However, if the file is absent from the tree of some commit, a simple `rm filename` will fail for that tree and commit. Thus you may instead want to use `rm -f filename` as the script. -Using `--index-filter` with 'git rm' yields a significantly faster +Using `--index-filter` with `git rm` yields a significantly faster version. Like with using `rm filename`, `git rm --cached filename` will fail if the file is absent from the tree of a commit. If you want to "completely forget" a file, it does not matter when it entered @@ -341,10 +341,10 @@ as their parents instead of the merge commit. *NOTE* the changes introduced by the commits, and which are not reverted by subsequent commits, will still be in the rewritten branch. If you want to throw out _changes_ together with the commits, you should use the -interactive mode of 'git rebase'. +interactive mode of `git rebase`. You can rewrite the commit log messages using `--msg-filter`. For -example, 'git svn-id' strings in a repository created by 'git svn' can +example, `git svn-id` strings in a repository created by `git svn` can be removed this way: ------------------------------------------------------- @@ -383,7 +383,7 @@ git filter-branch --env-filter ' To restrict rewriting to only part of the history, specify a revision range in addition to the new branch name. The new branch name will -point to the top-most revision that a 'git rev-list' of this range +point to the top-most revision that a `git rev-list` of this range will print. Consider this history: @@ -422,7 +422,7 @@ git filter-branch --index-filter \ CHECKLIST FOR SHRINKING A REPOSITORY ------------------------------------ -git-filter-branch can be used to get rid of a subset of files, +`git-filter-branch` can be used to get rid of a subset of files, usually with some combination of `--index-filter` and `--subdirectory-filter`. People expect the resulting repository to be smaller than the original, but you need a few more steps to @@ -434,7 +434,7 @@ objects until you tell it to. First make sure that: can help you find renames. * You really filtered all refs: use `--tag-name-filter cat -- --all` - when calling git-filter-branch. + when calling `git-filter-branch`. Then there are two ways to get a smaller repository. A safer way is to clone, that keeps your original intact. @@ -448,30 +448,30 @@ following points instead (in this order). This is a very destructive approach, so *make a backup* or go back to cloning it. You have been warned. -* Remove the original refs backed up by git-filter-branch: say `git +* Remove the original refs backed up by `git-filter-branch`: say `git for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d`. * Expire all reflogs with `git reflog expire --expire=now --all`. * Garbage collect all unreferenced objects with `git gc --prune=now` - (or if your git-gc is not new enough to support arguments to + (or if your `git-gc` is not new enough to support arguments to `--prune`, use `git repack -ad; git prune` instead). [[PERFORMANCE]] PERFORMANCE ----------- -The performance of git-filter-branch is glacially slow; its design makes it +The performance of `git-filter-branch` is glacially slow; its design makes it impossible for a backward-compatible implementation to ever be fast: -* In editing files, git-filter-branch by design checks out each and +* In editing files, `git-filter-branch` by design checks out each and every commit as it existed in the original repo. If your repo has `10^5` files and `10^5` commits, but each commit only modifies five - files, then git-filter-branch will make you do `10^10` modifications, + files, then `git-filter-branch` will make you do `10^10` modifications, despite only having (at most) `5*10^5` unique blobs. -* If you try and cheat and try to make git-filter-branch only work on +* If you try and cheat and try to make `git-filter-branch` only work on files modified in a commit, then two things happen ** you run into problems with deletions whenever the user is simply @@ -490,16 +490,16 @@ impossible for a backward-compatible implementation to ever be fast: remove some and thus can avoid checking out each file (i.e. you can use --index-filter), you still are passing shell snippets for your filters. This means that for every commit, you have to have a - prepared git repo where those filters can be run. That's a + prepared `git` repo where those filters can be run. That's a significant setup. * Further, several additional files are created or updated per commit - by git-filter-branch. Some of these are for supporting the - convenience functions provided by git-filter-branch (such as map()), + by `git-filter-branch`. Some of these are for supporting the + convenience functions provided by `git-filter-branch` (such as map()), while others are for keeping track of internal state (but could have also been accessed by user filters; one of git-filter-branch's regression tests does so). This essentially amounts to using the - filesystem as an IPC mechanism between git-filter-branch and the + filesystem as an IPC mechanism between `git-filter-branch` and the user-provided filters. Disks tend to be a slow IPC mechanism, and writing these files also effectively represents a forced synchronization point between separate processes that we hit with @@ -511,46 +511,46 @@ impossible for a backward-compatible implementation to ever be fast: of time between operating systems, but on any platform it is very slow relative to invoking a function. -* git-filter-branch itself is written in shell, which is kind of slow. +* `git-filter-branch` itself is written in shell, which is kind of slow. This is the one performance issue that could be backward-compatibly fixed, but compared to the above problems that are intrinsic to the - design of git-filter-branch, the language of the tool itself is a + design of `git-filter-branch`, the language of the tool itself is a relatively minor issue. ** Side note: Unfortunately, people tend to fixate on the - written-in-shell aspect and periodically ask if git-filter-branch + written-in-shell aspect and periodically ask if `git-filter-branch` could be rewritten in another language to fix the performance issues. Not only does that ignore the bigger intrinsic problems with the design, it'd help less than you'd expect: if - git-filter-branch itself were not shell, then the convenience + `git-filter-branch` itself were not shell, then the convenience functions (map(), skip_commit(), etc) and the `--setup` argument could no longer be executed once at the beginning of the program but would instead need to be prepended to every user filter (and thus re-executed with every commit). The https://github.com/newren/git-filter-repo/[git filter-repo] tool is -an alternative to git-filter-branch which does not suffer from these +an alternative to `git-filter-branch` which does not suffer from these performance problems or the safety problems (mentioned below). For those -with existing tooling which relies upon git-filter-branch, 'git -filter-repo' also provides +with existing tooling which relies upon `git-filter-branch`, `git +filter-repo` also provides https://github.com/newren/git-filter-repo/blob/master/contrib/filter-repo-demos/filter-lamely[filter-lamely], -a drop-in git-filter-branch replacement (with a few caveats). While +a drop-in `git-filter-branch` replacement (with a few caveats). While filter-lamely suffers from all the same safety issues as -git-filter-branch, it at least ameliorates the performance issues a +`git-filter-branch`, it at least ameliorates the performance issues a little. [[SAFETY]] SAFETY ------ -git-filter-branch is riddled with gotchas resulting in various ways to +`git-filter-branch` is riddled with gotchas resulting in various ways to easily corrupt repos or end up with a mess worse than what you started with: * Someone can have a set of "working and tested filters" which they document or provide to a coworker, who then runs them on a different OS where the same commands are not working/tested (some examples in - the git-filter-branch manpage are also affected by this). + the `git-filter-branch` manpage are also affected by this). BSD vs. GNU userland differences can really bite. If lucky, error messages are spewed. But just as likely, the commands either don't do the filtering requested, or silently corrupt by making some @@ -563,7 +563,7 @@ with: * Filenames with spaces are often mishandled by shell snippets since they cause problems for shell pipelines. Not everyone is familiar - with find -print0, xargs -0, git-ls-files -z, etc. Even people who + with `find -print0`, `xargs -0`, `git-ls-files -z`, etc. Even people who are familiar with these may assume such flags are not relevant because someone else renamed any such files in their repo back before the person doing the filtering joined the project. And @@ -590,7 +590,7 @@ with: problem.) * It's far too easy to accidentally mix up old and new history. It's - still possible with any tool, but git-filter-branch almost + still possible with any tool, but `git-filter-branch` almost invites it. If lucky, the only downside is users getting frustrated that they don't know how to shrink their repo and remove the old stuff. If unlucky, they merge old and new history and end up with @@ -612,7 +612,7 @@ with: need to understand that they need to rebase their changes for all their branches on top of new history (or delete and reclone), but that's only one of multiple concerns to consider. See the - "DISCUSSION" section of the git filter-repo manual page for more + "DISCUSSION" section of the `git filter-repo` manual page for more details. * Annotated tags can be accidentally converted to lightweight tags, @@ -620,16 +620,16 @@ with: ** Someone can do a history rewrite, realize they messed up, restore from the backups in refs/original/, and then redo their - git-filter-branch command. (The backup in refs/original/ is not a + `git-filter-branch` command. (The backup in refs/original/ is not a real backup; it dereferences tags first.) - ** Running git-filter-branch with either `--tags` or `--all` in your + ** Running `git-filter-branch` with either `--tags` or `--all` in your <rev-list options>. In order to retain annotated tags as annotated, you must use `--tag-name-filter` (and must not have restored from refs/original/ in a previously botched rewrite). * Any commit messages that specify an encoding will become corrupted - by the rewrite; git-filter-branch ignores the encoding, takes the + by the rewrite; `git-filter-branch` ignores the encoding, takes the original bytes, and feeds it to commit-tree without telling it the proper encoding. (This happens whether or not `--msg-filter` is used.) @@ -665,12 +665,12 @@ with: update authors and committers, missing taggers. * If the user provides a `--tag-name-filter` that maps multiple tags to - the same name, no warning or error is provided; git-filter-branch + the same name, no warning or error is provided; `git-filter-branch` simply overwrites each tag in some undocumented pre-defined order - resulting in only one tag at the end. (A git-filter-branch + resulting in only one tag at the end. (A `git-filter-branch` regression test requires this surprising behavior.) -Also, the poor performance of git-filter-branch often leads to safety +Also, the poor performance of `git-filter-branch` often leads to safety issues: * Coming up with the correct shell snippet to do the filtering you @@ -681,7 +681,7 @@ issues: circumstances (spaces in filenames, non-ascii filenames, funny author names or emails, invalid timezones, presence of grafts or replace objects, etc.), meaning they may have to wait a long time, - hit an error, then restart. The performance of git-filter-branch is + hit an error, then restart. The performance of `git-filter-branch` is so bad that this cycle is painful, reducing the time available to carefully re-check (to say nothing about what it does to the patience of the person doing the rewrite even if they do technically diff --git a/Documentation/git-fmt-merge-msg.txt b/Documentation/git-fmt-merge-msg.txt index 86fb26dcea..a8e9ab914d 100644 --- a/Documentation/git-fmt-merge-msg.txt +++ b/Documentation/git-fmt-merge-msg.txt @@ -9,17 +9,17 @@ git-fmt-merge-msg - Produce a merge commit message SYNOPSIS -------- [verse] -'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] -'git fmt-merge-msg' [-m <message>] [--log[=<n>] | --no-log] -F <file> +`git fmt-merge-msg` [-m <message>] [--log[=<n>] | --no-log] +`git fmt-merge-msg` [-m <message>] [--log[=<n>] | --no-log] -F <file> DESCRIPTION ----------- Takes the list of merged objects on stdin and produces a suitable commit message to be used for the merge commit, usually to be -passed as the '<merge-message>' argument of 'git merge'. +passed as the '<merge-message>' argument of `git merge`. This command is intended mostly for internal use by scripts -automatically invoking 'git merge'. +automatically invoking `git merge`. OPTIONS ------- diff --git a/Documentation/git-for-each-ref.txt b/Documentation/git-for-each-ref.txt index 64ff4a14f8..33fb379df4 100644 --- a/Documentation/git-for-each-ref.txt +++ b/Documentation/git-for-each-ref.txt @@ -8,7 +8,7 @@ git-for-each-ref - Output information on each ref SYNOPSIS -------- [verse] -'git for-each-ref' [--count=<count>] [--shell|--perl|--python|--tcl] +`git for-each-ref` [--count=<count>] [--shell|--perl|--python|--tcl] [(--sort=<key>)...] [--format=<format>] [<pattern>...] [--points-at=<object>] [--merged[=<object>]] [--no-merged[=<object>]] @@ -125,7 +125,7 @@ objecttype:: The type of the object (`blob`, `tree`, `commit`, `tag`). objectsize:: - The size of the object (the same as 'git cat-file -s' reports). + The size of the object (the same as `git cat-file -s` reports). Append `:disk` to get the size, in bytes, that the object takes up on disk. See the note about on-disk sizes in the `CAVEATS` section below. objectname:: diff --git a/Documentation/git-for-each-repo.txt b/Documentation/git-for-each-repo.txt index 94bd19da26..c2d6cd6629 100644 --- a/Documentation/git-for-each-repo.txt +++ b/Documentation/git-for-each-repo.txt @@ -9,7 +9,7 @@ git-for-each-repo - Run a Git command on a list of repositories SYNOPSIS -------- [verse] -'git for-each-repo' --config=<config> [--] <arguments> +`git for-each-repo` --config=<config> [--] <arguments> DESCRIPTION diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt index fd7c6c705b..2009a048a9 100644 --- a/Documentation/git-format-patch.txt +++ b/Documentation/git-format-patch.txt @@ -9,7 +9,7 @@ git-format-patch - Prepare patches for e-mail submission SYNOPSIS -------- [verse] -'git format-patch' [-k] [(-o|--output-directory) <dir> | --stdout] +`git format-patch` [-k] [(-o|--output-directory) <dir> | --stdout] [--no-thread | --thread[=<style>]] [(--attach|--inline)[=<boundary>] | --no-attach] [-s | --signoff] @@ -39,7 +39,7 @@ DESCRIPTION Prepare each commit with its "patch" in one "message" per commit, formatted to resemble a UNIX mailbox. The output of this command is convenient for e-mail submission or -for use with 'git am'. +for use with `git am`. A "message" generated by the command consists of three parts: @@ -176,7 +176,7 @@ The default is `--no-thread`, unless the `format.thread` configuration is set. If `--thread` is specified without a style, it defaults to the style specified by `format.thread` if any, or else `shallow`. + -Beware that the default for 'git send-email' is to thread emails +Beware that the default for `git send-email` is to thread emails itself. If you want `git format-patch` to take care of threading, you will want to ensure that threading is disabled for `git send-email`. @@ -415,7 +415,7 @@ with configuration variables. DISCUSSION ---------- -The patch produced by 'git format-patch' is in UNIX mailbox format, +The patch produced by `git format-patch` is in UNIX mailbox format, with a fixed "magic" time stamp to indicate that the file is output from format-patch rather than a real mailbox, like so: @@ -444,8 +444,8 @@ can save interesting patches in a UNIX mailbox and apply them with linkgit:git-am[1]. When a patch is part of an ongoing discussion, the patch generated by -'git format-patch' can be tweaked to take advantage of the 'git am ---scissors' feature. After your response to the discussion comes a +`git format-patch` can be tweaked to take advantage of the `git am +--scissors` feature. After your response to the discussion comes a line that consists solely of "`-- >8 --`" (scissors and perforation), followed by the patch with unnecessary header fields removed: @@ -524,11 +524,11 @@ GMail ~~~~~ GMail does not have any way to turn off line wrapping in the web interface, so it will mangle any emails that you send. You can however -use "git send-email" and send your patches through the GMail SMTP server, or +use `git send-email` and send your patches through the GMail SMTP server, or use any IMAP email client to connect to the google IMAP server and forward the emails through that. -For hints on using 'git send-email' to send your patches through the +For hints on using `git send-email` to send your patches through the GMail SMTP server, see the EXAMPLE section of linkgit:git-send-email[1]. For hints on submission using the IMAP interface, see the EXAMPLE @@ -551,7 +551,7 @@ Install the Toggle Word Wrap add-on that is available from https://addons.mozilla.org/thunderbird/addon/toggle-word-wrap/ It adds a menu entry "Enable Word Wrap" in the composer's "Options" menu that you can tick off. Now you can compose the message as you otherwise do -(cut + paste, 'git format-patch' | 'git imap-send', etc), but you have to +(cut + paste, `git format-patch` | `git imap-send`, etc), but you have to insert line breaks manually in any text that you type. Approach #2 (configuration) @@ -579,7 +579,7 @@ Toggle it to make sure it is set to `false`. Also, search for Toggle it to make sure it is set to `false`. After that is done, you should be able to compose email as you -otherwise would (cut + paste, 'git format-patch' | 'git imap-send', etc), +otherwise would (cut + paste, `git format-patch` | `git imap-send`, etc), and the patches will not be mangled. Approach #3 (external editor) @@ -699,7 +699,7 @@ EXAMPLES -------- * Extract commits between revisions R1 and R2, and apply them on top of - the current branch using 'git am' to cherry-pick them: + the current branch using `git am` to `cherry-pick` them: + ------------ $ git format-patch -k --stdout R1..R2 | git am -3 -k diff --git a/Documentation/git-fsck-objects.txt b/Documentation/git-fsck-objects.txt index eec4bdb600..589bb63fdc 100644 --- a/Documentation/git-fsck-objects.txt +++ b/Documentation/git-fsck-objects.txt @@ -9,7 +9,7 @@ git-fsck-objects - Verifies the connectivity and validity of the objects in the SYNOPSIS -------- [verse] -'git fsck-objects' ... +`git fsck-objects` ... DESCRIPTION ----------- diff --git a/Documentation/git-fsck.txt b/Documentation/git-fsck.txt index d9a28e278d..048a28ee50 100644 --- a/Documentation/git-fsck.txt +++ b/Documentation/git-fsck.txt @@ -9,7 +9,7 @@ git-fsck - Verifies the connectivity and validity of the objects in the database SYNOPSIS -------- [verse] -'git fsck' [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] +`git fsck` [--tags] [--root] [--unreachable] [--cache] [--no-reflogs] [--[no-]full] [--strict] [--verbose] [--lost-found] [--[no-]dangling] [--[no-]progress] [--connectivity-only] [--[no-]name-objects] [<object>*] @@ -23,7 +23,7 @@ OPTIONS <object>:: An object to treat as the head of an unreachability trace. + -If no objects are given, 'git fsck' defaults to using the +If no objects are given, `git fsck` defaults to using the index file, all SHA-1 references in `refs` namespace, and all reflogs (unless `--no-reflogs` is given) as heads. @@ -112,7 +112,7 @@ include::config/fsck.txt[] DISCUSSION ---------- -git-fsck tests SHA-1 and general object sanity, and it does full tracking +`git-fsck` tests SHA-1 and general object sanity, and it does full tracking of the resulting reachability and everything else. It prints out any corruption it finds (missing or bad objects), and if you use the `--unreachable` flag it will also print out objects that exist but that @@ -124,7 +124,7 @@ Any corrupt objects you will have to find in backups or other archives the hopes that somebody else has the object you have corrupted). If `core.commitGraph` is true, the commit-graph file will also be inspected -using 'git commit-graph verify'. See linkgit:git-commit-graph[1]. +using `git commit-graph verify`. See linkgit:git-commit-graph[1]. Extracted Diagnostics --------------------- diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 9d27c3a41e..c5c71febf5 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -9,14 +9,14 @@ git-gc - Cleanup unnecessary files and optimize the local repository SYNOPSIS -------- [verse] -'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack] +`git gc` [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack] DESCRIPTION ----------- Runs a number of housekeeping tasks within the current repository, such as compressing file revisions (to reduce disk space and increase performance), removing unreachable objects which may have been -created from prior invocations of 'git add', packing refs, pruning +created from prior invocations of `git add`, packing refs, pruning reflog, rerere metadata or stale working trees. May also update ancillary indexes such as the commit-graph. @@ -35,14 +35,14 @@ OPTIONS ------- --aggressive:: - Usually 'git gc' runs very quickly while providing good disk + Usually `git gc` runs very quickly while providing good disk space utilization and performance. This option will cause - 'git gc' to more aggressively optimize the repository at the expense + `git gc` to more aggressively optimize the repository at the expense of taking much more time. The effects of this optimization are mostly persistent. See the "AGGRESSIVE" section below for details. --auto:: - With this option, 'git gc' checks whether any housekeeping is + With this option, `git gc` checks whether any housekeeping is required; if not, it exits without performing any work. + See the `gc.auto` option in the "CONFIGURATION" section below for how @@ -114,19 +114,19 @@ include::config/gc.txt[] NOTES ----- -'git gc' tries very hard not to delete objects that are referenced +`git gc` tries very hard not to delete objects that are referenced anywhere in your repository. In particular, it will keep not only objects referenced by your current set of branches and tags, but also objects referenced by the index, remote-tracking branches, reflogs (which may reference commits in branches that were later amended or rewound), and anything else in the refs/* namespace. Note that a note -(of the kind created by 'git notes') attached to an object does not +(of the kind created by `git notes`) attached to an object does not contribute in keeping the object alive. If you are expecting some objects to be deleted and they aren't, check all of those locations and decide whether it makes sense in your case to remove those references. -On the other hand, when 'git gc' runs concurrently with another process, +On the other hand, when `git gc` runs concurrently with another process, there is a risk of it deleting an object that the other process is using but hasn't created a reference to. This may just cause the other process to fail or may corrupt the repository if the other process later adds a @@ -147,7 +147,7 @@ seems to be low in practice). HOOKS ----- -The 'git gc --auto' command will run the 'pre-auto-gc' hook. See +The `git gc --auto` command will run the 'pre-auto-gc' hook. See linkgit:githooks[5] for more information. diff --git a/Documentation/git-get-tar-commit-id.txt b/Documentation/git-get-tar-commit-id.txt index ac44d85b0b..7b7e41bf68 100644 --- a/Documentation/git-get-tar-commit-id.txt +++ b/Documentation/git-get-tar-commit-id.txt @@ -9,20 +9,20 @@ git-get-tar-commit-id - Extract commit ID from an archive created using git-arch SYNOPSIS -------- [verse] -'git get-tar-commit-id' +`git get-tar-commit-id` DESCRIPTION ----------- -Read a tar archive created by 'git archive' from the standard input +Read a tar archive created by `git archive` from the standard input and extract the commit ID stored in it. It reads only the first 1024 bytes of input, thus its runtime is not influenced by the size of the tar archive very much. -If no commit ID is found, 'git get-tar-commit-id' quietly exists with a +If no commit ID is found, `git get-tar-commit-id` quietly exists with a return code of 1. This can happen if the archive had not been created -using 'git archive' or if the first parameter of 'git archive' had been +using `git archive` or if the first parameter of `git archive` had been a tree ID instead of a commit ID or tag. GIT diff --git a/Documentation/git-grep.txt b/Documentation/git-grep.txt index 88047cefad..b10a3f6bb4 100644 --- a/Documentation/git-grep.txt +++ b/Documentation/git-grep.txt @@ -9,7 +9,7 @@ git-grep - Print lines matching a pattern SYNOPSIS -------- [verse] -'git grep' [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp] +`git grep` [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp] [-v | --invert-match] [-h|-H] [--full-name] [-E | --extended-regexp] [-G | --basic-regexp] [-P | --perl-regexp] @@ -66,8 +66,8 @@ grep.fullName:: If set to true, enable `--full-name` option by default. grep.fallbackToNoIndex:: - If set to true, fall back to git grep `--no-index` if git grep - is executed outside of a git repository. Defaults to false. + If set to true, fall back to `git grep --no-index` if `git grep` + is executed outside of a `git` repository. Defaults to false. OPTIONS @@ -191,13 +191,13 @@ providing this option will cause it to die. --files-without-match:: Instead of showing every matched line, show only the names of files that contain (or do not contain) matches. - For better compatibility with 'git diff', `--name-only` is a + For better compatibility with `git diff`, `--name-only` is a synonym for `--files-with-matches`. -O[<pager>]:: --open-files-in-pager[=<pager>]:: Open the matching files in the pager (not the output of 'grep'). - If the pager happens to be "less" or "vi", and the user + If the pager happens to be `less` or `vi`, and the user specified only one pattern, the first file is positioned at the first match automatically. The `pager` argument is optional; if specified, it must be stuck to the option diff --git a/Documentation/git-gui.txt b/Documentation/git-gui.txt index c9d7e96214..ff66c5b1d0 100644 --- a/Documentation/git-gui.txt +++ b/Documentation/git-gui.txt @@ -8,23 +8,23 @@ git-gui - A portable graphical interface to Git SYNOPSIS -------- [verse] -'git gui' [<command>] [arguments] +`git gui` [<command>] [arguments] DESCRIPTION ----------- -A Tcl/Tk based graphical user interface to Git. 'git gui' focuses +A Tcl/Tk based graphical user interface to Git. `git gui` focuses on allowing users to make changes to their repository by making new commits, amending existing ones, creating branches, performing local merges, and fetching/pushing to remote repositories. -Unlike 'gitk', 'git gui' focuses on commit generation +Unlike `gitk`, `git gui` focuses on commit generation and single file annotation and does not show project history. -It does however supply menu actions to start a 'gitk' session from -within 'git gui'. +It does however supply menu actions to start a `gitk` session from +within `git gui`. -'git gui' is known to work on all popular UNIX systems, Mac OS X, +`git gui` is known to work on all popular UNIX systems, Mac OS X, and Windows (under both Cygwin and MSYS). To the extent possible -OS specific user interface guidelines are followed, making 'git gui' +OS specific user interface guidelines are followed, making `git gui` a fairly native interface for users. COMMANDS @@ -39,13 +39,13 @@ browser:: browser are opened in the blame viewer. citool:: - Start 'git gui' and arrange to make exactly one commit before + Start `git gui` and arrange to make exactly one commit before exiting and returning to the shell. The interface is limited to only commit actions, slightly reducing the application's startup time and simplifying the menubar. version:: - Display the currently running version of 'git gui'. + Display the currently running version of `git gui`. Examples @@ -103,16 +103,16 @@ SEE ALSO -------- linkgit:gitk[1]:: The Git repository browser. Shows branches, commit history - and file differences. gitk is the utility started by + and file differences. `gitk` is the utility started by 'git gui''s Repository Visualize actions. Other ----- -'git gui' is actually maintained as an independent project, but stable +`git gui` is actually maintained as an independent project, but stable versions are distributed as part of the Git suite for the convenience of end users. -The official repository of the 'git gui' project can be found at: +The official repository of the `git gui` project can be found at: https://github.com/prati0100/git-gui.git/ diff --git a/Documentation/git-hash-object.txt b/Documentation/git-hash-object.txt index df9e2c58bd..15c2945345 100644 --- a/Documentation/git-hash-object.txt +++ b/Documentation/git-hash-object.txt @@ -9,8 +9,8 @@ git-hash-object - Compute object ID and optionally creates a blob from a file SYNOPSIS -------- [verse] -'git hash-object' [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>... -'git hash-object' [-t <type>] [-w] --stdin-paths [--no-filters] +`git hash-object` [-t <type>] [-w] [--path=<file>|--no-filters] [--stdin [--literally]] [--] <file>... +`git hash-object` [-t <type>] [-w] --stdin-paths [--no-filters] DESCRIPTION ----------- @@ -54,7 +54,7 @@ OPTIONS --literally:: Allow `--stdin` to hash any garbage into a loose object which might not - otherwise pass standard object parsing or git-fsck checks. Useful for + otherwise pass standard object parsing or `git-fsck` checks. Useful for stress-testing Git itself or reproducing characteristics of corrupt or bogus objects encountered in the wild. diff --git a/Documentation/git-help.txt b/Documentation/git-help.txt index 392f7be6fa..2d5660f47a 100644 --- a/Documentation/git-help.txt +++ b/Documentation/git-help.txt @@ -8,13 +8,13 @@ git-help - Display help information about Git SYNOPSIS -------- [verse] -'git help' [-a|--all [--[no-]verbose]] [-g|--guides] +`git help` [-a|--all [--[no-]verbose]] [-g|--guides] [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE] DESCRIPTION ----------- -With no options and no COMMAND or GUIDE given, the synopsis of the 'git' +With no options and no COMMAND or GUIDE given, the synopsis of the `git` command and a list of the most commonly used Git commands are printed on the standard output. @@ -29,7 +29,7 @@ guide is brought up. The 'man' program is used by default for this purpose, but this can be overridden by other options or configuration variables. -If an alias is given, git shows the definition of the alias on +If an alias is given, `git` shows the definition of the alias on standard output. To get the manual page for the aliased command, use `git COMMAND --help`. @@ -38,7 +38,7 @@ former is internally converted into the latter. To display the linkgit:git[1] man page, use `git help git`. -This page can be displayed with 'git help help' or `git help --help` +This page can be displayed with `git help help` or `git help --help` OPTIONS ------- @@ -83,8 +83,8 @@ other display programs (see below). + The web browser can be specified using the configuration variable `help.browser`, or `web.browser` if the former is not set. If none of -these config variables is set, the 'git web{litdd}browse' helper script -(called by 'git help') will pick a suitable default. See +these config variables is set, the `git web--browse` helper script +(called by `git help`) will pick a suitable default. See linkgit:git-web{litdd}browse[1] for more information about this. CONFIGURATION VARIABLES @@ -95,7 +95,7 @@ help.format If no command-line option is passed, the `help.format` configuration variable will be checked. The following values are supported for this -variable; they make 'git help' behave as their corresponding command- +variable; they make `git help` behave as their corresponding command- line option: * "man" corresponds to `-m`|`--man`, @@ -150,7 +150,7 @@ man.<tool>.path You can explicitly provide a full path to your preferred man viewer by setting the configuration variable `man.<tool>.path`. For example, you can configure the absolute path to konqueror by setting -`man.konqueror.path`. Otherwise, 'git help' assumes the tool is +`man.konqueror.path`. Otherwise, `git help` assumes the tool is available in PATH. man.<tool>.cmd @@ -185,7 +185,7 @@ the following: cmd = A_PATH_TO/konqueror ------------------------------------------------ -Note about git config --global +Note about `git config --global` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note that all these configuration variables should probably be set diff --git a/Documentation/git-http-backend.txt b/Documentation/git-http-backend.txt index 558966aa83..c97c10ba09 100644 --- a/Documentation/git-http-backend.txt +++ b/Documentation/git-http-backend.txt @@ -8,7 +8,7 @@ git-http-backend - Server side implementation of Git over HTTP SYNOPSIS -------- [verse] -'git http-backend' +`git http-backend` DESCRIPTION ----------- @@ -19,15 +19,15 @@ and the backwards-compatible dumb HTTP protocol, as well as clients pushing using the smart HTTP protocol. It verifies that t