delta/git.git/Documentation/git-cat-file.txt, branch ds/commit-graph

cat-file doc: document that -e will return some output

2018-01-10T23:08:14+00:00

The -e option added in 7950571ad7 ("A few more options for
git-cat-file", 2005-12-03) has always errored out with message on
stderr saying that the provided object is malformed, like this:

    $ git cat-file -e malformed; echo $?
    fatal: Not a valid object name malformed
    128

A reader of this documentation may be misled into thinking that

    if ! git cat-file -e "$object" [...]

as opposed to:

    if ! git cat-file -e "$object" 2>/dev/null [...]

is sufficient to implement a truly silent test that checks whether
some arbitrary $object string was both valid, and pointed to an
object that exists.

Signed-off-by: Ævar Arnfjörð Bjarmason 
Signed-off-by: Junio C Hamano

doc: fix minor typos (extra/duplicated words)

2017-09-14T06:09:02+00:00

Following are several fixes for duplicated words ("of of") and one
case where an extra article ("a") slipped in.

Signed-off-by: Evan Zacks 
Signed-off-by: Junio C Hamano

cat-file: support --textconv/--filters in batch mode

2016-09-11T21:48:15+00:00

With this patch, --batch can be combined with --textconv or --filters.
For this to work, the input needs to have the form

	

so that the filters can be chosen appropriately.

Signed-off-by: Johannes Schindelin 
Signed-off-by: Junio C Hamano

cat-file --textconv/--filters: allow specifying the path separately

2016-09-11T21:48:15+00:00

There are circumstances when it is relatively easy to figure out the
object name for a given path, but not the name of the containing tree.
For example, when looking at a diff generated by Git, the object names
are recorded, but not the revision. As a matter of fact, the revisions
from which the diff was generated may not even exist locally.

In such a case, the user would have to generate a fake revision just to
be able to use --textconv or --filters.

Let's simplify this dramatically, because we do not really need that
revision at all: all we care about is that we know the path. In the
scenario described above, we do know the path, and we just want to
specify it separately from the object name.

Example usage:

	git cat-file --textconv --path=main.c 0f1937fd

Signed-off-by: Johannes Schindelin 
Signed-off-by: Junio C Hamano

cat-file: introduce the --filters option

2016-09-11T21:47:46+00:00

The --filters option applies the convert_to_working_tree() filter for
the path when showing the contents of a regular file blob object;
the contents are written out as-is for other types of objects.

This feature comes in handy when a 3rd-party tool wants to work with
the contents of files from past revisions as if they had been checked
out, but without detouring via temporary files.

Signed-off-by: Johannes Schindelin 
Signed-off-by: Junio C Hamano

cat-file: fix a grammo in the man page

2016-08-24T16:09:28+00:00

"... has be ..." -> "... has to be ..."

Signed-off-by: Johannes Schindelin 
Signed-off-by: Junio C Hamano

doc: typeset long command-line options as literal

2016-06-28T15:36:45+00:00

Similarly to the previous commit, use backquotes instead of
forward-quotes, for long options.

This was obtained with:

  perl -pi -e "s/'(--[a-z][a-z=<>-]*)'/\`\$1\`/g" *.txt

and manual tweak to remove false positive in ascii-art (o'--o'--o' to
describe rewritten history).

Signed-off-by: Matthieu Moy 
Signed-off-by: Junio C Hamano

doc: typeset short command-line options as literal

2016-06-28T15:20:52+00:00

It was common in our documentation to surround short option names with
forward quotes, which renders as italic in HTML. Instead, use backquotes
which renders as monospace. This is one more step toward conformance to
Documentation/CodingGuidelines.

This was obtained with:

  perl -pi -e "s/'(-[a-z])'/\`\$1\`/g" *.txt

Signed-off-by: Matthieu Moy 
Signed-off-by: Junio C Hamano

usage: do not insist that standard input must come from a file

2015-10-16T22:27:52+00:00

The synopsys text and the usage string of subcommands that read list
of things from the standard input are often shown like this:

	git gostak [--distim] < 

This is problematic in a number of ways:

 * The way to use these commands is more often to feed them the
   output from another command, not feed them from a file.

 * Manual pages outside Git, commands that operate on the data read
   from the standard input, e.g "sort", "grep", "sed", etc., are not
   described with such a "< redirection-from-file" in their synopsys
   text.  Our doing so introduces inconsistency.

 * We do not insist on where the output should go, by saying

	git gostak [--distim] <  > 

 * As it is our convention to enclose placeholders inside ,
   the redirection operator followed by a placeholder filename
   becomes very hard to read, both in the documentation and in the
   help text.

Let's clean them all up, after making sure that the documentation
clearly describes the modes that take information from the standard
input and what kind of things are expected on the input.

[jc: stole example for fmt-merge-msg from Jonathan]

Helped-by: Jonathan Nieder 
Signed-off-by: Junio C Hamano

cat-file: sort and de-dup output of --batch-all-objects

2015-06-26T16:24:42+00:00

The sorting we could probably live without, but printing
duplicates is just a hassle for the user, who must then
de-dup themselves (or risk a wrong answer if they are doing
something like counting objects with a particular property).

Signed-off-by: Jeff King 
Signed-off-by: Junio C Hamano