user/sven/git.git/Documentation/git-reset.txt, branch v1.8.0.2

docs: stop using asciidoc no-inline-literal

2012-04-26T20:19:06Z

In asciidoc 7, backticks like `foo` produced a typographic effect, but did not otherwise affect the syntax. In asciidoc 8, backticks introduce an "inline literal" inside which markup is not interpreted. To keep compatibility with existing documents, asciidoc 8 has a "no-inline-literal" attribute to keep the old behavior. We enabled this so that the documentation could be built on either version. It has been several years now, and asciidoc 7 is no longer in wide use. We can now decide whether or not we want inline literals on their own merits, which are: 1. The source is much easier to read when the literal contains punctuation. You can use `master~1` instead of `master{tilde}1`. 2. They are less error-prone. Because of point (1), we tend to make mistakes and forget the extra layer of quoting. This patch removes the no-inline-literal attribute from the Makefile and converts every use of backticks in the documentation to an inline literal (they must be cleaned up, or the example above would literally show "{tilde}" in the output). Problematic sites were found by grepping for '`.*[{\\]' and examined and fixed manually. The results were then verified by comparing the output of "html2text" on the set of generated html pages. Doing so revealed that in addition to making the source more readable, this patch fixes several formatting bugs: - HTML rendering used the ellipsis character instead of literal "..." in code examples (like "git log A...B") - some code examples used the right-arrow character instead of '->' because they failed to quote - api-config.txt did not quote tilde, and the resulting HTML contained a bogus snippet like: foo bar which caused some parsers to choke and omit whole sections of the page. - git-commit.txt confused ``foo`` (backticks inside a literal) with ``foo'' (matched double-quotes) - mentions of `A U Thor ` used to erroneously auto-generate a mailto footnote for author@example.com - the description of --word-diff=plain incorrectly showed the output as "[-removed-] and {added}", not "{+added+}". - using "prime" notation like: commit `C` and its replacement `C'` confused asciidoc into thinking that everything between the first backtick and the final apostrophe were meant to be inside matched quotes - asciidoc got confused by the escaping of some of our asterisks. In particular, `credential.\*` and `credential..\*` properly escaped the asterisk in the first case, but literally passed through the backslash in the second case. Signed-off-by: Jeff King Signed-off-by: Junio C Hamano

builtin-reset: Documentation update

2011-11-23T21:24:54Z

The second mode of 'git reset' is defined by the --patch option, while the third mode is defined by the option. Hence, these options are mandatory in the description of the individual modes. Signed-off-by: Vincent van Ravesteijn Signed-off-by: Junio C Hamano

git-reset.txt: better docs for '--patch'

2011-05-05T20:31:22Z

Describe '-p' as a short form of '--patch' in synopsis. Also include a better explanation of this option and additionally refer the reader to the patch mode description of git-add documentation. Helped-by: Jeff King Mentored-by: Junio C Hamano Signed-off-by: Valentin Haenel Signed-off-by: Junio C Hamano

doc: drop author/documentation sections from most pages

2011-03-11T15:59:16Z

The point of these sections is generally to: 1. Give credit where it is due. 2. Give the reader an idea of where to ask questions or file bug reports. But they don't do a good job of either case. For (1), they are out of date and incomplete. A much more accurate answer can be gotten through shortlog or blame. For (2), the correct contact point is generally git@vger, and even if you wanted to cc the contact point, the out-of-date and incomplete fields mean you're likely sending to somebody useless. So let's drop the fields entirely from all manpages except git(1) itself. We already point people to the mailing list for bug reports there, and we can update the Authors section to give credit to the major contributors and point to shortlog and blame for more information. Each page has a "This is part of git" footer, so people can follow that to the main git manpage.

Documentation: do not treat reset --keep as a special case

2011-01-21T20:41:14Z

The current treatment of "git reset --keep" emphasizes how it differs from --hard (treatment of local changes) and how it breaks down into plumbing (git read-tree -m -u HEAD followed by git update-ref HEAD ). This can discourage people from using it, since it might seem to be a complex or niche option. Better to emphasize what the --keep flag is intended for --- moving the index and worktree from one commit to another, like "git checkout" would --- so the reader can make a more informed decision about the appropriate situations in which to use it. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano

git-reset.txt: make modes description more consistent

2010-09-18T22:14:41Z

Currently, the structure of the individual mode entries is different which makes it difficult to grasp the differences between the modes. Also, the same items are named differently (e.g. , "the named commit", "the given commit", "the commit being switched to"). Structure and word all mode entries consistently. Signed-off-by: Michael J Gruber Signed-off-by: Junio C Hamano

git-reset.txt: point to git-checkout

2010-09-18T22:14:26Z

for the case of updating a file in index and worktree, or from the index to the worktree. Signed-off-by: Michael J Gruber Signed-off-by: Junio C Hamano

git-reset.txt: use "working tree" consistently

2010-09-18T22:14:24Z

as per git help glossary Signed-off-by: Michael J Gruber Signed-off-by: Junio C Hamano

git-reset.txt: reset --soft is not a no-op

2010-09-18T22:14:19Z

Make it clearer that git reset --soft actually does something (changing HEAD). While it is mentioned in the previous paragraph already it can be easily overlooked otherwise. Also, git reset --soft does not look at the index nor the worktree, so there is no "good order" requirement. Signed-off-by: Michael J Gruber Signed-off-by: Junio C Hamano

git-reset.txt: reset does not change files in target

2010-09-18T22:14:16Z

git-reset obviously cannot change files in an existing commit. Make it not sound as if it could: reset can change HEAD and, in that sense, can change which state a file in HEAD is in. Signed-off-by: Michael J Gruber Signed-off-by: Junio C Hamano