Replace double quotes around literal examples with backticks
Signed-off-by: NJason St. John <jstjohn@purdue.edu>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The way to spell the current repository with a '.' dot is
independent from how the pathspec allows globs expanded by Git.

Make them two separate bullet items in the enumeration.
Signed-off-by: NPhilip Oakley <philipoakley@iee.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The Git cli will accept dot '.' (period) as the relative path
to the current repository. Explain this action.
Signed-off-by: NPhilip Oakley <philipoakley@iee.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Replace 'committish' in documentation and comments with 'commit-ish'
to match gitglossary(7) and to be consistent with 'tree-ish'.

The only remaining instances of 'committish' are:
  * variable, function, and macro names
  * "(also committish)" in the definition of commit-ish in
    gitglossary[7]
Signed-off-by: NRichard Hansen <rhansen@bbn.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

A couple of references still survive to .git/refs as a tree
of all refs.  Fix one in docs, one in a -h message, one in
a -h message quoted in docs.
Signed-off-by: NGreg Price <price@mit.edu>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NThomas Ackermann <th.acker@arcor.de>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Describe the behaviour, but do warn people against taking it too
literally and expect an abbreviation valid today will stay valid
forever.
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

People who are not used to working with shell may intellectually
understand how the command line argument is massaged by the shell
but still have a hard time visualizing the difference between
letting the shell expand fileglobs and having Git see the fileglob
to use as a pathspec.
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

The paragraph to encourage use of "--" in scripts belongs to the
bullet point that describes the behaviour for a command line without
the explicit "--" disambiguation; it is not a supporting explanation
for the entire bulletted list, and it is wrong to make it a separate
paragraph outside the list.
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NJunio C Hamano <gitster@pobox.com>

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: NJeff King <peff@peff.net>
Signed-off-by: NJunio 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.

A sample "git describe -h" did not match what the program actually says.
Signed-off-by: NThiago Farina <tfransosi@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

If literal text (asciidoc `...`) can be rendered in a differently from
normal text for each output format (man, HTML), then we do not need
extra quotes or other wrapping around inline literal text segments.

config.txt

  Change '`...`' to `...`. In asciidoc, the single quotes provide
  emphasis, literal text should be distintive enough.

  Change "`...`" to `...`. These double quotes do not work if present
  in the described config value, so drop them.

git-checkout.txt

  Change "`...`" to `...` or `"..."`. All instances are command line
  argument examples. One "`-`" becomes `-`. Two others are involve
  curly braces, so move the double quotes inside the literal region to
  indicate that they might need to be quoted on the command line of
  certain shells (tcsh).

git-merge.txt

  Change "`...`" to `...`. All instances are used to describe merge
  conflict markers. The quotes should are not important.

git-rev-parse.txt

  Change "`...`" to `...`. All instances are around command line
  arguments where no in-shell quoting should be necessary.

gitcli.txt

  Change `"..."` to `...`. All instances are around command line
  examples or single command arguments. They do not semanticly belong
  inside the literal text, and they are not needed outside it.

glossary-content.txt
user-manual.txt

  Change "`...`" to `...`. All instances were around command lines.
Signed-off-by: NChris Johnsen <chris_johnsen@pobox.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

We saw this explanation repeated on the mailing list a few times.  Even
though the description of individual options to particular commands are
explained in their manual pages, the reason behind choosing which is which
has not been clearly explained in any of the documentation.
Signed-off-by: NNanako Shiraishi <nanako3@lavabit.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

This is a very well established command line convention that old residents
of the git mailing list knew by heart and nobody even thought about
documenting it explicitly, which was not very nice.
Signed-off-by: NJunio 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: NChristian Couder <chriscool@tuxfamily.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Also now "gitcli(5)" becomes "gitcli(7)".
Signed-off-by: NChristian Couder <chriscool@tuxfamily.org>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

Signed-off-by: NRalf Wildenhues <Ralf.Wildenhues@gmx.de>
Signed-off-by: NJunio 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: NDan McGee <dpmcgee@gmail.com>
Signed-off-by: NJunio C Hamano <gitster@pobox.com>

This page should hold every information about the git ways to parse command
lines, and best practices to be used for scripting.
Signed-off-by: NPierre Habouzit <madcoder@debian.org>