development/git
development/git
1
0
Fork 0
mirror of https://github.com/git/git synced 2024-10-06 00:29:28 +00:00
Code Issues Packages Projects Releases Wiki Activity
git/builtin
History
Štěpán Němec cebfaaa333 doc/cat-file: make synopsis and description less confusing 
The DESCRIPTION's "first form" is actually the 1st, 2nd, 3rd and 5th
form in SYNOPSIS, the "second form" is the 4th one.

Interestingly, this state of affairs was introduced in
97fe725075 (cat-file docs: fix SYNOPSIS and "-h" output, 2021-12-28)
with the claim of "Now the two will match again." ("the two" being
DESCRIPTION and SYNOPSIS)...

The description also suffers from other correctness and clarity issues,
e.g., the "first form" paragraph discusses -p, -s and -t, but leaves out
-e, which is included in the corresponding SYNOPSIS section; the second
paragraph mentions <format>, which doesn't occur in SYNOPSIS at all, and
of the three batch options, really only describes the behavior of
--batch-check.  Also the mention of "drivers" seems an implementation
detail not adding much clarity in a short summary (and isn't expanded
upon in the rest of the man page, either).

Rather than trying to maintain one-to-one (or N-to-M) correspondence
between the DESCRIPTION and SYNOPSIS forms, creating duplication and
providing opportunities for error, shorten the former into a concise
summary describing the two general modes of operation: batch and
non-batch, leaving details to the subsequent manual sections.

While here, fix a grammar error in the description of -e and make the
following further minor improvements:

  NAME:
    shorten ("content or type and size" isn't the whole story; say
    "details" and leave the actual details to later sections)

  SYNOPSIS and --help:
    move the (--textconv | --filters) form before --batch, closer
    to the other non-batch forms

Signed-off-by: Štěpán Němec <stepnem@smrk.net>
Acked-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2023-10-09 12:46:33 -07:00
..
add.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
am.c Merge branch 'jc/am-parseopt-fix' 2023-07-26 14:13:15 -07:00
annotate.c strvec: rename struct fields 2020-07-30 19:18:06 -07:00
apply.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
archive.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
bisect.c treewide: remove unnecessary includes for wrapper.h 2023-07-05 11:41:59 -07:00
blame.c Merge branch 'cw/compat-util-header-cleanup' 2023-07-17 11:30:42 -07:00
branch.c Merge branch 'jc/branch-parseopt-fix' 2023-07-26 14:13:15 -07:00
bugreport.c treewide: remove unnecessary includes for wrapper.h 2023-07-05 11:41:59 -07:00
bundle.c Merge branch 'rs/bundle-parseopt-cleanup' 2023-08-07 11:57:18 -07:00
cat-file.c doc/cat-file: make synopsis and description less confusing 2023-10-09 12:46:33 -07:00
check-attr.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
check-ignore.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
check-mailmap.c builtin.h: remove unneccessary includes 2023-06-21 13:39:54 -07:00
check-ref-format.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
checkout--worker.c git-compat-util: move alloc macros to git-compat-util.h 2023-07-05 11:42:31 -07:00
checkout-index.c read-cache*.h: move declarations for read-cache.c functions from cache.h 2023-06-21 13:39:53 -07:00
checkout.c Merge branch 'ah/advise-force-pushing' 2023-07-25 12:05:23 -07:00
clean.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
clone.c Merge branch 'jc/transport-parseopt-fix' 2023-07-27 15:26:37 -07:00
column.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
commit-graph.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
commit-tree.c object-store-ll.h: split this header out of object-store.h 2023-06-21 13:39:54 -07:00
commit.c Merge branch 'js/empty-index-fixes' 2023-07-08 11:23:07 -07:00
config.c Merge branch 'cw/compat-util-header-cleanup' 2023-07-17 11:30:42 -07:00
count-objects.c count-objects: mark unused parameter in alternates callback 2023-07-13 17:24:00 -07:00
credential-cache--daemon.c git-compat-util: move alloc macros to git-compat-util.h 2023-07-05 11:42:31 -07:00
credential-cache.c treewide: remove unnecessary includes for wrapper.h 2023-07-05 11:41:59 -07:00
credential-store.c Merge branch 'cw/strbuf-cleanup' 2023-07-06 11:54:46 -07:00
credential.c builtins: mark unused prefix parameters 2023-03-28 14:11:24 -07:00
describe.c Merge branch 'rs/describe-parseopt-fix' 2023-07-28 09:45:21 -07:00
diagnose.c object-file.h: move declarations for object-file.c functions from cache.h 2023-04-11 08:52:10 -07:00
diff-files.c diff.h: remove unnecessary include of oidset.h 2023-06-21 13:39:53 -07:00
diff-index.c Merge branch 'en/header-split-cache-h-part-3' 2023-06-29 16:43:21 -07:00
diff-tree.c revisions: drop unused "opt" parameter in "tweak" callbacks 2023-07-13 17:24:00 -07:00
diff.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
difftool.c Merge branch 'cw/compat-util-header-cleanup' 2023-07-17 11:30:42 -07:00
fast-export.c object-store-ll.h: split this header out of object-store.h 2023-06-21 13:39:54 -07:00
fast-import.c treewide: remove unnecessary includes for wrapper.h 2023-07-05 11:41:59 -07:00
fetch-pack.c git-compat-util: move alloc macros to git-compat-util.h 2023-07-05 11:42:31 -07:00
fetch.c Merge branch 'jc/transport-parseopt-fix' 2023-07-27 15:26:37 -07:00
fmt-merge-msg.c treewide: remove unnecessary includes for wrapper.h 2023-07-05 11:41:59 -07:00
for-each-ref.c Merge branch 'tb/refs-exclusion-and-packed-refs' 2023-07-21 13:47:26 -07:00
for-each-repo.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
fsck.c fsck: use enum object_type for fsck_walk callback 2023-08-19 21:17:32 -07:00
fsmonitor--daemon.c Merge branch 'cw/compat-util-header-cleanup' 2023-07-17 11:30:42 -07:00
gc.c Merge branch 'ds/maintenance-on-windows-fix' 2023-08-15 10:19:47 -07:00
get-tar-commit-id.c treewide: remove unnecessary includes for wrapper.h 2023-07-05 11:41:59 -07:00
grep.c Merge branch 'jc/tree-walk-drop-base-offset' 2023-08-02 09:37:23 -07:00
hash-object.c object-store-ll.h: split this header out of object-store.h 2023-06-21 13:39:54 -07:00
help.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
hook.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
index-pack.c Merge branch 'jk/unused-parameter' 2023-07-25 12:05:24 -07:00
init-db.c treewide: remove unnecessary includes for wrapper.h 2023-07-05 11:41:59 -07:00
interpret-trailers.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
log.c Merge branch 'jk/unused-parameter' 2023-07-25 12:05:24 -07:00
ls-files.c Merge branch 'rs/strbuf-expand-step' 2023-07-06 11:54:45 -07:00
ls-remote.c git-compat-util.h: remove unneccessary include of wildmatch.h 2023-06-21 13:39:54 -07:00
ls-tree.c ls-tree: fix --no-full-name 2023-07-18 09:38:24 -07:00
mailinfo.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
mailsplit.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
merge-base.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
merge-file.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
merge-index.c read-cache*.h: move declarations for read-cache.c functions from cache.h 2023-06-21 13:39:53 -07:00
merge-ours.c diff.h: remove unnecessary include of oidset.h 2023-06-21 13:39:53 -07:00
merge-recursive.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
merge-tree.c merge-tree: mark unused parameter in traverse callback 2023-07-13 17:24:00 -07:00
merge.c Merge branch 'cw/compat-util-header-cleanup' 2023-07-17 11:30:42 -07:00
mktag.c fsck: mark unused parameters in various fsck callbacks 2023-07-13 17:24:00 -07:00
mktree.c git-compat-util: move alloc macros to git-compat-util.h 2023-07-05 11:42:31 -07:00
multi-pack-index.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
mv.c Merge branch 'st/mv-lstat-fix' 2023-08-15 10:19:47 -07:00
name-rev.c git-compat-util: move alloc macros to git-compat-util.h 2023-07-05 11:42:31 -07:00
notes.c Merge branch 'tl/notes-separator' 2023-07-06 11:54:47 -07:00
pack-objects.c Merge branch 'rs/pack-objects-parseopt-fix' 2023-07-28 09:45:22 -07:00
pack-redundant.c object-store-ll.h: split this header out of object-store.h 2023-06-21 13:39:54 -07:00
pack-refs.c pack-refs: teach pack-refs --include option 2023-05-12 14:54:14 -07:00
patch-id.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
prune-packed.c treewide: be explicit about dependence on gettext.h 2023-03-21 10:56:51 -07:00
prune.c Merge branch 'en/header-split-cache-h-part-3' 2023-06-29 16:43:21 -07:00
pull.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
push.c Merge branch 'jc/transport-parseopt-fix' 2023-07-27 15:26:37 -07:00
range-diff.c diff.h: remove unnecessary include of oidset.h 2023-06-21 13:39:53 -07:00
read-tree.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
rebase.c Merge branch 'cw/compat-util-header-cleanup' 2023-07-17 11:30:42 -07:00
receive-pack.c Merge branch 'tb/refs-exclusion-and-packed-refs' 2023-07-21 13:47:26 -07:00
reflog.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
remote-ext.c builtins: annotate always-empty prefix parameters 2023-03-28 14:11:24 -07:00
remote-fd.c builtins: annotate always-empty prefix parameters 2023-03-28 14:11:24 -07:00
remote.c Merge branch 'jc/parse-options-short-help' 2023-08-04 10:52:31 -07:00
repack.c repack: free geometry struct 2023-08-08 16:49:10 -07:00
replace.c replace: mark unused parameter in each_mergetag_fn callback 2023-07-13 17:24:00 -07:00
rerere.c treewide: remove unnecessary includes for wrapper.h 2023-07-05 11:41:59 -07:00
reset.c Merge branch 'jc/parse-options-reset' 2023-07-27 15:26:37 -07:00
rev-list.c object-store-ll.h: split this header out of object-store.h 2023-06-21 13:39:54 -07:00
rev-parse.c Merge branch 'jk/unused-parameter' 2023-07-25 12:05:24 -07:00
revert.c git-compat-util: move alloc macros to git-compat-util.h 2023-07-05 11:42:31 -07:00
rm.c git-compat-util: move alloc macros to git-compat-util.h 2023-07-05 11:42:31 -07:00
send-pack.c config: add ctx arg to config_fn_t 2023-06-28 14:06:39 -07:00
shortlog.c diff.h: remove unnecessary include of oidset.h 2023-06-21 13:39:53 -07:00
show-branch.c Merge branch 'jc/parse-options-show-branch' 2023-07-27 15:26:37 -07:00
show-index.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
show-ref.c object-store-ll.h: split this header out of object-store.h 2023-06-21 13:39:54 -07:00
sparse-checkout.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
stash.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
stripspace.c Merge branch 'cw/strbuf-cleanup' 2023-07-06 11:54:46 -07:00
submodule--helper.c Merge branch 'cw/compat-util-header-cleanup' 2023-07-17 11:30:42 -07:00
symbolic-ref.c git-compat-util: move strbuf.c funcs to its header 2023-07-05 11:41:18 -07:00
tag.c Merge branch 'jk/unused-parameter' 2023-07-25 12:05:24 -07:00
unpack-file.c treewide: remove unnecessary includes for wrapper.h 2023-07-05 11:41:59 -07:00
unpack-objects.c Merge branch 'jk/unused-parameter' 2023-07-25 12:05:24 -07:00
update-index.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
update-ref.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
update-server-info.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
upload-archive.c repository: remove unnecessary include of path.h 2023-06-21 13:39:53 -07:00
upload-pack.c Merge branch 'en/header-split-cache-h-part-3' 2023-06-29 16:43:21 -07:00
var.c Merge branch 'gc/config-context' 2023-07-06 11:54:48 -07:00
verify-commit.c object-store-ll.h: split this header out of object-store.h 2023-06-21 13:39:54 -07:00
verify-pack.c builtin.h: remove unneccessary includes 2023-06-21 13:39:54 -07:00
verify-tag.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00
worktree.c Merge branch 'ja/worktree-orphan-fix' 2023-08-04 10:52:30 -07:00
write-tree.c cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00