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:
<tt><sub></tt> foo <tt></sub>bar</tt>
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 <author@example.com>` 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.<url>.\*`
properly escaped the asterisk in the first case, but
literally passed through the backslash in the second
case.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The --include-untracked option acts like the normal "git stash save" but
also adds all untracked files in the working directory to the stash and then
calls "git clean --force --quiet" to restore the working directory to a
pristine state.
This is useful for projects that need to run release scripts. With this
option, the release scripts can be from the main working directory so one
does not have to maintain a "clean" directory in parallel just for
releasing. Basically the work-flow becomes:
$ git tag release-1.0
$ git stash --include-untracked
$ make release
$ git clean -f
$ git stash pop
"git stash" alone is not enough in this case--it leaves untracked files
lying around that might mess up a release process that expects everything to
be very clean or might let a release succeed that should actually fail (due
to a new source file being created that hasn't been committed yet).
Signed-off-by: David Caldwell <david@porkrind.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Describe '-p' as a short form of '--patch' in synopsis and options. Also
refer the reader to the patch mode description of git-add documentation.
Helped-by: Jeff King <peff@peff.net>
Mentored-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Valentin Haenel <valentin.haenel@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
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.
Update the documentation to indicate that git stash branch only attempts
to drop the specified stash if it looks like stash reference.
Also changed the synopsis to more clearly indicate which commands require
a stash entry reference as opposed to merely a stash-like commit.
Signed-off-by: Jon Seymour <jon.seymour@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
It is misleading to say that we pull refs from $GIT_DIR/refs/*, because we
may also consult the packed refs mechanism. These days we tend to treat
the "refs hierarchy" as more of an abstract namespace that happens to be
represented as $GIT_DIR/refs. At best, this is a minor inaccuracy, but at
worst it can confuse users who then look in $GIT_DIR/refs and find that it
is missing some of the refs they expected to see.
This patch drops most uses of "$GIT_DIR/refs/*", changing them into just
"refs/*", under the assumption that users can handle the concept of an
abstract refs namespace. There are a few things to note:
- most cases just dropped the $GIT_DIR/ portion. But for cases where
that left _just_ the word "refs", I changed it to "refs/" to help
indicate that it was a hierarchy. I didn't do the same for longer
paths (e.g., "refs/heads" remained, instead of becoming
"refs/heads/").
- in some cases, no change was made, as the text was explicitly about
unpacked refs (e.g., the discussion in git-pack-refs).
- In some cases it made sense instead to note the existence of packed
refs (e.g., in check-ref-format and rev-parse).
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation was quite inconsistent when spelling 'git cmd' if it
only refers to the program, not to some specific invocation syntax:
both 'git-cmd' and 'git cmd' spellings exist.
The current trend goes towards dashless forms, and there is precedent
in 647ac70 (git-svn.txt: stop using dash-form of commands.,
2009-07-07) to actively eliminate the dashed variants.
Replace 'git-cmd' with 'git cmd' throughout, except where git-shell,
git-cvsserver, git-upload-pack, git-receive-pack, and
git-upload-archive are concerned, because those really live in the
$PATH.
Use `code snippet` style instead of 'emphasis' for `git cmd ...`
according to the following rules:
* The SYNOPSIS sections are left untouched.
* If the intent is that the user type the command exactly as given, it
is `code`.
If the user is only loosely referred to a command and/or option, it
remains 'emphasised'.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
'git stash list' had an undocumented limit of 10 stashes, unless other
git-log arguments were specified. This surprised at least one user,
but possibly served to cut the output below a screenful without using
a pager.
Since the last commit, 'git stash list' will fire up a pager according
to the same rules as the 'git log' it calls, so we can drop the limit.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
* tr/reset-checkout-patch:
stash: simplify defaulting to "save" and reject unknown options
Make test case number unique
tests: disable interactive hunk selection tests if perl is not available
DWIM 'git stash save -p' for 'git stash -p'
Implement 'git stash save --patch'
Implement 'git checkout --patch'
Implement 'git reset --patch'
builtin-add: refactor the meat of interactive_add()
Add a small patch-mode testing library
git-apply--interactive: Refactor patch mode code
Make 'git stash -k' a short form for 'git stash save --keep-index'
With the earlier DWIM patches, certain combination of options defaulted
to the "save" command correctly while certain equally valid combination
did not. For example, "git stash -k" were Ok but "git stash -q -k" did
not work.
This makes the logic of defaulting to "save" much simpler. If there are no
non-flag arguments, it is clear that there is no command word, and we
default to "save" subcommand. This rule prevents "git stash -q apply"
from quietly creating a stash with "apply" as the message.
This also teaches "git stash save" to reject an unknown option. This is
to keep a mistyped "git stash save --quite" from creating a stash with a
message "--quite", and this safety is more important with the new logic
to default to "save" with any option-looking argument without an explicit
comand word.
[jc: this is based on Matthieu's 3-patch series, and a follow-up
discussion, and he and Peff take all the credit; if I have introduced bugs
while reworking, they are mine.]
Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This adds a hunk-based mode to git-stash. You can select hunks from
the difference between HEAD and worktree, and git-stash will build a
stash that reflects these changes. The index state of the stash is
the same as your current index, and we also let --patch imply
--keep-index.
Note that because the selected hunks are rolled back from the worktree
but not the index, the resulting state may appear somewhat confusing
if you had also staged these changes. This is not entirely
satisfactory, but due to the way stashes are applied, other solutions
would require a change to the stash format.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Add an example to the stash documentation that shows how to quickly
find candidate commits among the 'git fsck --unreachable' output.
Unless you have merges of branch names containing WIP, or edit your
merge messages to say WIP, there will be no false positives.
Snippet written by Björn "doener" Steinbrink and me after zepolen_
asked on IRC.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
To save me from the carpal tunnel syndrome, make 'git stash' accept
the short option '-k' instead of '--keep-index', and for even more
convenience, let's DWIM when this developer forgot to type the 'save'
command.
Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Teach stash pop, apply, save, and drop to be quiet when told. By using
the quiet option (-q), these actions will be silent unless errors are
encountered.
Signed-off-by: Stephen Boyd <bebarino@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
'git stash pop' supports the '--index' option since its initial
implementation (bd56ff54, git-stash: add new 'pop' subcommand,
2008-02-22), but its documentation does not mention it explicitly.
Moreover, both the usage shown by 'git stash -h' and the synopsis
section in the man page imply that 'git stash pop' does not have an
'--index' option.
First, this patch corrects the usage and the synopsis section.
Second, the patch moves the description of the '--index' option to the
'git stash pop' section in the documentation, and refers to it from
the 'git stash apply' section. This way it follows the intentions of
commit d1836637 (Documentation: teach stash/pop workflow instead of
stash/apply, 2009-05-28), as all 'git stash pop'-related documentation
will be in one place without references to 'git stash apply'.
Signed-off-by: SZEDER Gábor <szeder@ira.uka.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Recent discussion on the list showed some comments in favour of a
stash/pop workflow:
http://marc.info/?l=git&m=124234911423358&w=2http://marc.info/?l=git&m=124235348327711&w=2
Change the stash documentation and examples to document pop in its own
right (and apply in terms of pop), and use stash/pop in the examples.
Signed-off-by: Thomas Rast <trast@student.ethz.ch>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
There is no need to explicitly pass the file to be committed to 'git
commit', because it's contents is already in the index.
Signed-off-by: SZEDER Gábor <szeder@ira.uka.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Asciidoc removes lines starting with a dot when creating manpages.
Since those lines were comments in use case examples showing shell
commands, preceed those lines with a hash sign.
Signed-off-by: SZEDER Gábor <szeder@ira.uka.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
"git stash -h" showed some incomplete and ugly usage information.
For example, the useful "--keep-index" option for "save" or the "--index"
option for "apply" were not shown. Also in the documentation synopsis they
were not shown, so that there is no incentive to scroll down and even see
that such options exist.
This patch improves the git-stash synopsis in the documentation by
mentioning that further options to the stash commands and then copies
this synopsis to the usage information string of git-stash.sh.
For the latter, the dashless git command string has to be inserted on the
second and the following usage lines. The code of this is taken from
git-sh-setup so that all lines will show the command string.
Note that the "create" command is not advertised at all now, because
it was not mentioned in git-stash.txt.
Signed-off-by: Stephan Beyer <s-beyer@gmx.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The documentation suggests using "git stash apply" in the
--keep-index workflow even though doing so will lead to clutter
in the stash. And given that the changes are about to be
committed anyway "git stash pop" is more sensible.
Additionally the text preceeding the example claims that it
works for "two or more commits", but the example itself is
really tailored for just two. Expanding it just a little
makes it clear how the procedure generalizes to N commits.
Finally the example is annotated with some commentary to
explain things on a line-by-line basis.
The names of git commands are not meant to be entered at the
commandline; they are just names. So we render them in italics,
as is usual for command names in manpages.
Using
doit () {
perl -e 'for (<>) { s/\`(git-[^\`.]*)\`/'\''\1'\''/g; print }'
}
for i in git*.txt config.txt diff*.txt blame*.txt fetch*.txt i18n.txt \
merge*.txt pretty*.txt pull*.txt rev*.txt urls*.txt
do
doit <"$i" >"$i+" && mv "$i+" "$i"
done
git diff
.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
'git stash save' saves local modifications to a new stash, and runs 'git
reset --hard' to revert them to a clean index and work tree. When the
'--keep-index' option is specified, after that 'git reset --hard' the
previous contents of the index is restored and the work tree is updated
to match the index. This option is useful if the user wants to commit
only parts of his local modifications, but wants to test those parts
before committing.
Also add support for the completion of the new option, and add an
example use case to the documentation.
Signed-off-by: SZEDER Gábor <szeder@ira.uka.de>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Restores the stashed state on a new branch rooted at the commit on which
the stash was originally created, so that conflicts caused by subsequent
changes on the original branch can be dealt with.
(Thanks to Junio for this nice idea.)
Signed-off-by: Abhijit Menon-Sen <ams@toroid.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Following what appears to be the predominant style, format
names of commands and commandlines both as `teletype text`.
While we're at it, add articles ("a" and "the") in some
places, italicize the name of the command in the manual page
synopsis line, and add a comma or two where it seems appropriate.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Since the git-* commands are not installed in $(bindir), using
"git-command <parameters>" in examples in the documentation is
not a good idea. On the other hand, it is nice to be able to
refer to each command using one hyphenated word. (There is no
escaping it, anyway: man page names cannot have spaces in them.)
This patch retains the dash in naming an operation, command,
program, process, or action. Complete command lines that can
be entered at a shell (i.e., without options omitted) are
made to use the dashless form.
The changes consist only of replacing some spaces with hyphens
and vice versa. After a "s/ /-/g", the unpatched and patched
versions are identical.
Signed-off-by: Jonathan Nieder <jrnieder@uchicago.edu>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
As the "git" man page describes the "git" command at the end-user
level, it seems better to move it to man section 1.
Signed-off-by: Christian Couder <chriscool@tuxfamily.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This combines the existing stash subcommands 'apply' and 'drop' to
allow a single stash entry to be applied and then dropped, in other
words 'popped', from the stash list.
Signed-off-by: Brandon Casey <casey@nrlssc.navy.mil>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This allows a single stash entry to be deleted. It takes an
optional argument which is a stash reflog entry. If no
arguments are supplied, it drops the most recent stash entry.
Signed-off-by: Brandon Casey <casey@nrlssc.navy.mil>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Adjust the command syntax to better reflect the call parameters:
[save] [message...] => [save [<message>]].
Signed-off-by: Jari Aalto <jari.aalto AT cante.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Between AsciiDoc 8.2.2 and 8.2.3, the following change was made to the stock
Asciidoc configuration:
@@ -149,7 +153,10 @@
# Inline macros.
# Backslash prefix required for escape processing.
# (?s) re flag for line spanning.
-(?su)[\\]?(?P<name>\w(\w|-)*?):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
+# Explicit so they can be nested.
+(?su)[\\]?(?P<name>(http|https|ftp|file|mailto|callto|image|link)):(?P<target>\S*?)(\[(?P<attrlist>.*?)\])=
+
# Anchor: [[[id]]]. Bibliographic anchor.
(?su)[\\]?\[\[\[(?P<attrlist>[\w][\w-]*?)\]\]\]=anchor3
# Anchor: [[id,xreflabel]]
This default regex now matches explicit values, and unfortunately in this
case gitlink was being matched by just 'link', causing the wrong inline
macro template to be applied. By renaming the macro, we can avoid being
matched by the wrong regex.
Signed-off-by: Dan McGee <dpmcgee@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
The command was recently updated to take message on the command line, but
this feature has not been documented.
Signed-off-by: Nanako Shiraishi <nanako3@bluebottle.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Asciidoc treats {foo} as an attribute to be substituted; if
'foo' doesn't exist as an attribute, then the entire line
gets dropped. When the literal {foo} is desired, \{foo} is
required.
The exceptions to this rule are:
- inside literal blocks
- if the 'foo' contains non-alphanumeric characters (e.g.,
{foo|bar} is assumed not to be an attribute)
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
Commit 9488e875 changed this from 'save' to 'list', but
missed this spot in the documentation.
Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
This describes the git-stash command.
I borrowed a few paragraphs from Johannes's version, and added a few
examples.
Signed-off-by: Nanako Shiraishi <nanako3@bluebottle.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
