Hello!
I've been reading http://www.kernel.org/pub/software/scm/git/docs/user-manual.html till late night and found that "--" prefixing options names (like in "git diff --cached") are replaced by asciidoc with a single unicode character "—" which makes them unsuitable for pasting them to a terminal.
I've cloned the git repository from git://git.kernel.org/pub/scm/git/git.git, made some changes to Documentation/user-manual.txt, tested the results and commited my work locally. The attached file is a result of running `git diff HEAD~1`.
My local log message: ------------------ asciidoc escaping of "--"
Asciidoc replaces "--" with "—" when not in verbatim mode. This is sometimes unwanted -- especially when citing command line options like "git diff --cached". This commit includes proper quotes in user-manual.txt. ------------------
Hope that's of any use.
Best regards, Piotr
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt index 645d752..66d0cca 100644 --- a/Documentation/user-manual.txt +++ b/Documentation/user-manual.txt @@ -527,8 +527,8 @@ $ git reset --hard fb47ddb2db... then test, run "bisect good" or "bisect bad" as appropriate, and continue. -Instead of "git bisect visualize" and then "git reset --hard -fb47ddb2db...", you might just want to tell git that you want to skip +Instead of "git bisect visualize" and then "+++git reset --hard +fb47ddb2db...+++", you might just want to tell git that you want to skip the current commit: ------------------------------------------------- @@ -660,7 +660,7 @@ You can also ask git log to show patches: $ git log -p ------------------------------------------------- -See the "--pretty" option in the linkgit:git-log[1] man page for more +See the "+++--pretty+++" option in the linkgit:git-log[1] man page for more display options. Note that git log starts with the most recent commit and works @@ -900,7 +900,7 @@ $ gitk $( git show-ref --heads ) --not $( git show-ref --tags ) ------------------------------------------------- (See linkgit:git-rev-parse[1] for explanations of commit-selecting -syntax such as `--not`.) +syntax such as `+++--not+++`.) [[making-a-release]] Creating a changelog and tarball for a software release @@ -1024,7 +1024,7 @@ at step 3, git maintains a snapshot of the tree's contents in a special staging area called "the index." At the beginning, the content of the index will be identical to -that of the HEAD. The command "git diff --cached", which shows +that of the HEAD. The command "+++git diff --cached+++", which shows the difference between the HEAD and the index, should therefore produce no output at that point. @@ -1572,7 +1572,7 @@ Recovering lost changes Reflogs ^^^^^^^ -Say you modify a branch with `linkgit:git-reset[1] --hard`, and then +Say you modify a branch with `linkgit:git-reset[1] +++--hard+++`, and then realize that the branch was the only reference you had to that point in history. @@ -1701,7 +1701,7 @@ $ git pull More generally, a branch that is created from a remote branch will pull by default from that branch. See the descriptions of the branch.<name>.remote and branch.<name>.merge options in -linkgit:git-config[1], and the discussion of the `--track` option in +linkgit:git-config[1], and the discussion of the `+++--track+++` option in linkgit:git-checkout[1], to learn how to control these defaults. In addition to saving you keystrokes, "git pull" also helps you by @@ -1978,8 +1978,8 @@ error: failed to push to 'ssh://yourserver.com/~you/proj.git' This can happen, for example, if you: - - use `git-reset --hard` to remove already-published commits, or - - use `git-commit --amend` to replace already-published commits + - use `+++git-reset --hard+++` to remove already-published commits, or + - use `+++git-commit --amend+++` to replace already-published commits (as in <<fixing-a-mistake-by-rewriting-history>>), or - use `git-rebase` to rebase any already-published commits (as in <<using-git-rebase>>). @@ -2088,7 +2088,7 @@ linkgit:git-fetch[1] to keep them up-to-date; see Now create the branches in which you are going to work; these start out at the current tip of origin/master branch, and should be set up (using -the --track option to linkgit:git-branch[1]) to merge changes in from +the +++--track+++ option to linkgit:git-branch[1]) to merge changes in from Linus by default. ------------------------------------------------- @@ -2468,7 +2468,7 @@ $ git rebase --continue and git will continue applying the rest of the patches. -At any point you may use the `--abort` option to abort this process and +At any point you may use the `+++--abort+++` option to abort this process and return mywork to the state it had before you started the rebase: ------------------------------------------------- @@ -2539,7 +2539,7 @@ $ gitk origin..mywork & and browse through the list of patches in the mywork branch using gitk, applying them (possibly in a different order) to mywork-new using -cherry-pick, and possibly modifying them as you go using `commit --amend`. +cherry-pick, and possibly modifying them as you go using `+++commit --amend+++`. The linkgit:git-gui[1] command may also help as it allows you to individually select diff hunks for inclusion in the index (by right-clicking on the diff hunk and choosing "Stage Hunk for Commit"). @@ -2897,7 +2897,7 @@ Commit Object ~~~~~~~~~~~~~ The "commit" object links a physical state of a tree with a description -of how we got there and why. Use the --pretty=raw option to +of how we got there and why. Use the +++--pretty=raw+++ option to linkgit:git-show[1] or linkgit:git-log[1] to examine your favorite commit: @@ -3700,16 +3700,16 @@ i.e. it will normally just update existing cache entries. To tell git that yes, you really do realize that certain files no longer exist, or that new files should be added, you -should use the `--remove` and `--add` flags respectively. +should use the `+++--remove+++` and `+++--add+++` flags respectively. -NOTE! A `--remove` flag does 'not' mean that subsequent filenames will +NOTE! A `+++--remove+++` flag does 'not' mean that subsequent filenames will necessarily be removed: if the files still exist in your directory structure, the index will be updated with their new status, not -removed. The only thing `--remove` means is that update-index will be +removed. The only thing `+++--remove+++` means is that update-index will be considering a removed file to be a valid thing, and if the file really does not exist any more, it will update the index accordingly. -As a special case, you can also do `git update-index --refresh`, which +As a special case, you can also do `+++git update-index --refresh+++`, which will refresh the "stat" information of each index to match the current stat information. It will 'not' update the object status itself, and it will only update the fields that are used to quickly test whether @@ -3956,7 +3956,7 @@ entries" in it. Such an index tree can 'NOT' be written out to a tree object, and you will have to resolve any such merge clashes using other tools before you can write out the result. -You can examine such index state with `git ls-files --unmerged` +You can examine such index state with `+++git ls-files --unmerged+++` command. An example: ------------------------------------------------ @@ -3967,7 +3967,7 @@ $ git ls-files --unmerged 100644 cc44c73eb783565da5831b4d820c962954019b69 3 hello.c ------------------------------------------------ -Each line of the `git ls-files --unmerged` output begins with +Each line of the `+++git ls-files --unmerged+++` output begins with the blob mode bits, blob SHA1, 'stage number', and the filename. The 'stage number' is git's way to say which tree it came from: stage 1 corresponds to `$orig` tree, stage 2 `HEAD`
