git/Documentation
Š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
..
RelNotes Git 2.42 2023-08-21 09:34:58 -07:00
config Merge branch 'tb/gc-recent-object-hook' 2023-06-23 11:21:17 -07:00
howto new-command.txt: update reference to builtin docs 2023-02-06 14:07:33 -08:00
includes docs: add and use include template for config/* includes 2022-09-07 09:46:05 -07:00
mergetools vimdiff: add tool documentation 2022-04-03 15:09:52 -07:00
technical Merge branch 'en/header-split-cache-h-part-3' 2023-06-29 16:43:21 -07:00
.gitattributes
…
.gitignore doc: remove manpage-base-url workaround 2023-04-05 14:18:53 -07:00
CodingGuidelines Merge branch 'en/header-split-cache-h-part-3' 2023-06-29 16:43:21 -07:00
Makefile Merge branch 'fc/doc-stop-using-manversion' 2023-04-21 15:35:04 -07:00
MyFirstContribution.txt Merge branch 'jc/doc-sent-patch-now-what' 2023-08-04 10:52:31 -07:00
MyFirstObjectWalk.txt Merge branch 'vd/adjust-mfow-doc-to-updated-headers' 2023-07-17 11:30:42 -07:00
ReviewingGuidelines.txt Documentation: add ReviewingGuidelines 2022-09-19 14:36:08 -07:00
SubmittingPatches SubmittingPatches: use of older maintenance tracks is an exception 2023-07-27 13:07:40 -07:00
ToolsForGit.txt Documentation/ToolsForGit.txt: Tools for developing Git 2022-04-21 09:50:25 -07:00
asciidoc.conf doc: asciidoc: remove custom header macro 2023-04-05 21:37:45 -07:00
asciidoctor-extensions.rb
…
blame-options.txt blame: use different author name for fake commit generated by --contents 2023-04-24 15:16:31 -07:00
build-docdep.perl Documentation/build-docdep.perl: generate sorted output 2022-10-21 11:39:38 -07:00
cat-texi.perl
…
cmd-list.perl cmd-list.perl: fix identifying man sections 2022-09-23 10:01:07 -07:00
config.txt docs: typofixes 2023-06-12 13:52:51 -07:00
date-formats.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
diff-format.txt diff-format.txt: correct misleading wording 2022-06-13 11:57:03 -07:00
diff-generate-patch.txt docs: link generating patch sections 2023-01-13 12:55:14 -08:00
diff-options.txt Merge branch 'jc/diff-s-with-other-options' 2023-06-13 12:29:45 -07:00
doc-diff doc-diff: drop SOURCE_DATE_EPOCH override 2023-05-05 14:28:03 -07:00
docbook-xsl.css
…
docbook.xsl
…
everyday.txto
…
fetch-options.txt fetch: introduce machine-parseable "porcelain" output format 2023-05-10 10:35:25 -07:00
fix-texi.perl
…
fsck-msgids.txt fsck: document the new `gitattributes` message IDs 2023-01-16 12:03:14 -08:00
git-add.txt docs & comments: replace mentions of "git-add--interactive.perl" 2023-02-06 15:03:34 -08:00
git-am.txt am: refer to format-patch in the documentation 2023-03-21 13:18:45 -07:00
git-annotate.txt doc txt & -h consistency: make "annotate" consistent 2022-10-13 09:32:57 -07:00
git-apply.txt Documentation: render dash correctly 2023-01-23 09:40:14 -08:00
git-archimport.txt doc: split placeholders as individual tokens 2021-10-28 09:57:09 -07:00
git-archive.txt archive: add --mtime 2023-02-18 09:29:13 -08:00
git-bisect-lk2009.txt git-bisect-lk2009: update nist report link 2023-01-13 11:58:51 -08:00
git-bisect.txt docs: update when `git bisect visualize` uses `gitk` 2023-08-04 09:47:10 -07:00
git-blame.txt blame: allow --contents to work with non-HEAD commit 2023-03-24 12:05:22 -07:00
git-branch.txt branch, for-each-ref, tag: add option to omit empty lines 2023-04-13 08:07:45 -07:00
git-bugreport.txt builtin/bugreport.c: create '--diagnose' option 2022-08-12 13:20:02 -07:00
git-bundle.txt Merge branch 'jk/bundle-use-dash-for-stdfiles' 2023-03-19 15:03:12 -07:00
git-cat-file.txt doc/cat-file: make synopsis and description less confusing 2023-10-09 12:46:33 -07:00
git-check-attr.txt attr: add flag `--source` to work with tree-ish 2023-01-14 08:49:55 -08:00
git-check-ignore.txt doc: check-ignore: code-quote an exclamation mark 2022-02-03 11:13:49 -08:00
git-check-mailmap.txt
…
git-check-ref-format.txt
…
git-checkout-index.txt checkout-index: add --ignore-skip-worktree-bits option 2022-01-13 13:49:45 -08:00
git-checkout.txt doc: git-checkout: reorganize examples 2023-04-18 15:47:13 -07:00
git-cherry-pick.txt git-cherry-pick.txt: do not use 'ORIG_HEAD' in example 2023-01-13 09:55:45 -08:00
git-cherry.txt
…
git-citool.txt
…
git-clean.txt Merge branch 'ab/doc-synopsis-and-cmd-usage' 2022-10-28 11:26:54 -07:00
git-clone.txt clone: error specifically with --local and symlinked objects 2023-04-11 08:46:09 -07:00
git-column.txt docs: add CONFIGURATION sections that fuzzy map to built-ins 2022-09-07 09:46:07 -07:00
git-commit-graph.txt Merge branch 'ab/doc-synopsis-and-cmd-usage' 2022-10-28 11:26:54 -07:00
git-commit-tree.txt
…
git-commit.txt docs: add CONFIGURATION sections that map to a built-in 2022-09-07 09:46:06 -07:00
git-config.txt Documentation: define protected configuration 2022-07-14 15:08:29 -07:00
git-count-objects.txt
…
git-credential-cache--daemon.txt doc txt & -h consistency: fix mismatching labels 2022-10-13 09:32:56 -07:00
git-credential-cache.txt Documentation: clarify that cache forgets credentials if the system restarts 2023-01-29 09:21:07 -08:00
git-credential-store.txt
…
git-credential.txt credential: erase all matching credentials 2023-06-15 13:26:41 -07:00
git-cvsexportcommit.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-cvsimport.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-cvsserver.txt docs: typofixes 2023-06-12 13:52:51 -07:00
git-daemon.txt daemon: clarify directory arguments 2022-07-19 12:45:31 -07:00
git-describe.txt docs: typofixes 2023-06-12 13:52:51 -07:00
git-diagnose.txt builtin/diagnose.c: add '--mode' option 2022-08-12 13:20:02 -07:00
git-diff-files.txt doc txt & -h consistency: correct padding around "[]()" 2022-10-13 09:32:55 -07:00
git-diff-index.txt diff-index.txt: update raw output format in examples 2022-06-13 11:59:16 -07:00
git-diff-tree.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-diff.txt Documentation: document AUTO_MERGE 2023-05-23 17:21:47 +09:00
git-difftool.txt mergetool: new config guiDefault supports auto-toggling gui by DISPLAY 2023-04-05 21:03:29 -07:00
git-fast-export.txt doc SYNOPSIS: consistently use ' for commands 2022-10-13 09:32:54 -07:00
git-fast-import.txt docs: add CONFIGURATION sections that map to a built-in 2022-09-07 09:46:06 -07:00
git-fetch-pack.txt builtin/fetch-pack: add --refetch option 2022-03-28 10:25:52 -07:00
git-fetch.txt fetch: introduce machine-parseable "porcelain" output format 2023-05-10 10:35:25 -07:00
git-filter-branch.txt
…
git-fmt-merge-msg.txt merge: allow to pretend a merge is made into a different branch 2021-12-20 14:55:02 -08:00
git-for-each-ref.txt Merge branch 'ks/ref-filter-describe' 2023-08-02 09:37:24 -07:00
git-for-each-repo.txt
…
git-format-patch.txt docs: typofixes 2023-06-12 13:52:51 -07:00
git-fsck-objects.txt
…
git-fsck.txt fsck: document msg-id 2022-10-25 15:44:18 -07:00
git-fsmonitor--daemon.txt fsmonitor: add documentation for allowRemote and socketDir options 2022-10-05 11:05:23 -07:00
git-gc.txt builtin/gc.c: make `gc.cruftPacks` enabled by default 2023-04-18 14:56:48 -07:00
git-get-tar-commit-id.txt
…
git-grep.txt grep docs: de-duplicate configuration sections 2022-09-07 09:46:05 -07:00
git-gui.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-hash-object.txt docs: add git hash-object -t option's possible values 2023-06-28 23:00:10 -07:00
git-help.txt git docs: add a category for file formats, protocols and interfaces 2022-08-04 14:12:23 -07:00
git-hook.txt hook: support a --to-stdin=<path> option 2023-02-08 12:50:03 -08:00
git-http-backend.txt
…
git-http-fetch.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
git-http-push.txt doc: git-http-push: describe the refs as pattern pairs 2021-11-09 09:39:11 -08:00
git-imap-send.txt docs: add and use include template for config/* includes 2022-09-07 09:46:05 -07:00
git-index-pack.txt index-pack: document and test the --promisor option 2022-03-09 10:25:26 -08:00
git-init-db.txt doc: use only hyphens as word separators in placeholders 2021-11-09 09:39:11 -08:00
git-init.txt docs: add CONFIGURATION sections that fuzzy map to built-ins 2022-09-07 09:46:07 -07:00
git-instaweb.txt
…
git-interpret-trailers.txt doc: trailer: add more examples in DESCRIPTION 2023-06-14 21:42:20 -07:00
git-log.txt Merge branch 'ab/dedup-config-and-command-docs' 2022-09-14 12:56:40 -07:00
git-ls-files.txt ls-files: align format atoms with ls-tree 2023-05-23 20:12:57 +09:00
git-ls-remote.txt ls-remote doc: document the output format 2023-05-19 08:19:34 -07:00
git-ls-tree.txt Merge branch 'rs/doc-ls-tree-hex-literal' 2023-06-22 16:29:07 -07:00
git-mailinfo.txt docs: add CONFIGURATION sections that map to a built-in 2022-09-07 09:46:06 -07:00
git-mailsplit.txt
…
git-maintenance.txt maintenance: add option to register in a specific config 2022-11-14 22:39:25 -05:00
git-merge-base.txt doc txt & -h consistency: correct padding around "[]()" 2022-10-13 09:32:55 -07:00
git-merge-file.txt update documentation for new zdiff3 conflictStyle 2021-12-01 14:45:59 -08:00
git-merge-index.txt doc: use three dots for indicating repetition instead of star 2021-11-09 09:39:11 -08:00
git-merge-one-file.txt
…
git-merge-tree.txt Merge branch 'as/doc-markup-fix' 2023-03-19 15:03:11 -07:00
git-merge.txt Documentation: document AUTO_MERGE 2023-05-23 17:21:47 +09:00
git-mergetool--lib.txt
…
git-mergetool.txt mergetool: new config guiDefault supports auto-toggling gui by DISPLAY 2023-04-05 21:03:29 -07:00
git-mktag.txt docs: typofixes 2023-06-12 13:52:51 -07:00
git-mktree.txt fix typo in git-mktree.txt 2022-02-02 14:50:09 -08:00
git-multi-pack-index.txt midx.c: prevent `expire` from removing the cruft pack 2022-09-21 10:21:46 -07:00
git-mv.txt doc txt & -h consistency: fix mismatching labels 2022-10-13 09:32:56 -07:00
git-name-rev.txt name-rev: make --stdin hidden 2023-05-06 14:32:20 -07:00
git-notes.txt notes doc: tidy up `--no-stripspace` paragraph 2023-08-16 11:37:25 -07:00
git-p4.txt git-p4: improve encoding handling to support inconsistent encodings 2022-05-04 10:30:01 -07:00
git-pack-objects.txt builtin/pack-objects.c: --cruft without expiration 2022-05-26 15:48:26 -07:00
git-pack-redundant.txt pack-redundant: document deprecation 2023-03-30 07:50:43 -07:00
git-pack-refs.txt pack-refs: teach pack-refs --include option 2023-05-12 14:54:14 -07:00
git-patch-id.txt builtin: patch-id: add --verbatim as a command mode 2022-10-24 15:44:20 -07:00
git-prune-packed.txt doc txt & -h consistency: correct padding around "[]()" 2022-10-13 09:32:55 -07:00
git-prune.txt
…
git-pull.txt Merge branch 'js/retire-preserve-merges' 2021-10-18 15:47:56 -07:00
git-push.txt push: introduce '--branches' option 2023-05-06 14:36:43 -07:00
git-quiltimport.txt
…
git-range-diff.txt range-diff: optionally accept pathspecs 2022-08-26 09:49:26 -07:00
git-read-tree.txt Documentation: render dash correctly 2023-01-23 09:40:14 -08:00
git-rebase.txt rebase: add a config option for --rebase-merges 2023-03-27 09:32:49 -07:00
git-receive-pack.txt doc txt & -h consistency: use "git foo" form, not "git-foo" 2022-10-13 09:32:57 -07:00
git-reflog.txt reflog doc: list real subcommands up-front 2022-10-13 09:32:58 -07:00
git-remote-ext.txt
…
git-remote-fd.txt
…
git-remote-helpers.txto
…
git-remote.txt builtin/remote.c: teach `-v` to list filters for promisor remotes 2022-05-09 10:53:58 -07:00
git-repack.txt builtin/repack.c: implement `--expire-to` for storing pruned objects 2022-10-24 13:39:42 -07:00
git-replace.txt
…
git-request-pull.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
git-rerere.txt doc txt & -h consistency: make "rerere" consistent 2022-10-13 09:32:56 -07:00
git-reset.txt git-reset.txt: mention 'ORIG_HEAD' in the Description 2023-01-13 09:55:45 -08:00
git-restore.txt update documentation for new zdiff3 conflictStyle 2021-12-01 14:45:59 -08:00
git-rev-list.txt doc txt & -h consistency: add or fix optional "--" syntax 2022-10-13 09:32:56 -07:00
git-rev-parse.txt fetch: support hideRefs to speed up connectivity checks 2023-02-27 09:27:03 -08:00
git-revert.txt Merge branch 'ab/doc-synopsis-and-cmd-usage' 2022-11-29 10:41:06 +09:00
git-rm.txt
…
git-send-email.txt Merge branch 'mc/send-email-header-cmd' 2023-05-15 13:59:03 -07:00
git-send-pack.txt doc txt & -h consistency: add missing options and labels 2022-10-13 09:32:56 -07:00
git-sh-i18n--envsubst.txt
…
git-sh-i18n.txt
…
git-sh-setup.txt
…
git-shell.txt
…
git-shortlog.txt shortlog: support arbitrary commit format `--group`s 2022-10-24 14:48:05 -07:00
git-show-branch.txt show-branch doc: say <ref>, not <reference> 2023-05-19 08:19:34 -07:00
git-show-index.txt
…
git-show-ref.txt show-ref doc: fix carets in monospace 2023-08-16 11:40:10 -07:00
git-show.txt
…
git-sparse-checkout.txt docs: typofixes 2023-06-12 13:52:51 -07:00
git-stage.txt doc: express grammar placeholders between angle brackets 2021-11-09 09:39:11 -08:00
git-stash.txt docs: typofixes 2023-06-12 13:52:51 -07:00
git-status.txt status: modernize git-status "slow untracked files" advice 2022-12-01 15:27:41 +09:00
git-stripspace.txt
…
git-submodule.txt doc: highlight that .gitmodules does not support !command 2023-07-25 14:55:07 -07:00
git-svn.txt Merge branch 'ja/doc-cleanup' 2021-12-10 14:35:03 -08:00
git-switch.txt docs: add CONFIGURATION sections that fuzzy map to built-ins 2022-09-07 09:46:07 -07:00
git-symbolic-ref.txt symbolic-ref: teach "--[no-]recurse" option 2022-10-09 12:31:24 -07:00
git-tag.txt doc: tag: document `TAG_EDITMSG` 2023-05-16 11:38:14 -07:00
git-tools.txt
…
git-unpack-file.txt
…
git-unpack-objects.txt
…
git-update-index.txt Documentation: fix various repeat word typos 2022-09-12 11:04:55 -07:00
git-update-ref.txt
…
git-update-server-info.txt doc txt & -h consistency: add missing options and labels 2022-10-13 09:32:56 -07:00
git-upload-archive.txt doc txt & -h consistency: fix mismatching labels 2022-10-13 09:32:56 -07:00
git-upload-pack.txt Documentation: fix various repeat word typos 2022-09-12 11:04:55 -07:00
git-var.txt var: add config file locations 2023-06-27 11:31:06 -07:00
git-verify-commit.txt doc txt & -h consistency: add missing options and labels 2022-10-13 09:32:56 -07:00
git-verify-pack.txt doc txt & -h consistency: correct padding around "[]()" 2022-10-13 09:32:55 -07:00
git-verify-tag.txt doc txt & -h consistency: add missing options and labels 2022-10-13 09:32:56 -07:00
git-version.txt
…
git-web--browse.txt doc: split placeholders as individual tokens 2021-10-28 09:57:09 -07:00
git-whatchanged.txt
…
git-worktree.txt worktree add: extend DWIM to infer --orphan 2023-05-17 15:55:25 -07:00
git-write-tree.txt
…
git.txt doc: sha256 is no longer experimental 2023-07-31 09:11:04 -07:00
gitattributes.txt ll-merge: killing the external merge driver aborts the merge 2023-06-23 09:27:10 -07:00
gitcli.txt git-cli.txt: clarify "options first and then args" 2022-01-17 11:42:25 -08:00
gitcore-tutorial.txt
…
gitcredentials.txt Merge branch 'mh/doc-credential-helpers' 2023-07-18 07:28:52 -07:00
gitcvs-migration.txt
…
gitdiffcore.txt
…
giteveryday.txt
…
gitfaq.txt
…
gitformat-bundle.txt docs: move protocol-related docs to man section 5 2022-08-04 14:12:23 -07:00
gitformat-chunk.txt docs: move pack format docs to man section 5 2022-08-04 14:12:24 -07:00
gitformat-commit-graph.txt doc: use "commit-graph" hyphenation consistently 2022-10-30 19:58:40 -04:00
gitformat-index.txt docs: document zero bits in index "mode" 2023-02-01 08:49:23 -08:00
gitformat-pack.txt builtin/gc.c: make `gc.cruftPacks` enabled by default 2023-04-18 14:56:48 -07:00
gitformat-signature.txt Merge branch 'gm/signature-format-doc' 2023-03-06 21:51:56 -08:00
gitglossary.txt
…
githooks.txt Merge branch 'ms/send-email-feed-header-to-validate-hook' 2023-05-10 10:23:28 -07:00
gitignore.txt Merge branch 'jc/gitignore-doc-pattern-markup' 2023-07-27 15:26:37 -07:00
gitk.txt
…
gitmailmap.txt
…
gitmodules.txt doc: highlight that .gitmodules does not support !command 2023-07-25 14:55:07 -07:00
gitnamespaces.txt
…
gitprotocol-capabilities.txt docs: fix a few recently broken links 2022-09-16 08:38:03 -07:00
gitprotocol-common.txt docs: move protocol-related docs to man section 5 2022-08-04 14:12:23 -07:00
gitprotocol-http.txt docs: move http-protocol docs to man section 5 2022-08-04 14:12:24 -07:00
gitprotocol-pack.txt docs: move http-protocol docs to man section 5 2022-08-04 14:12:24 -07:00
gitprotocol-v2.txt *: fix typos which duplicate a word 2023-01-08 10:28:34 +09:00
gitremote-helpers.txt remote-curl: add 'get' capability 2022-08-10 14:07:37 -07:00
gitrepository-layout.txt
…
gitrevisions.txt
…
gitsubmodules.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
gittutorial-2.txt
…
gittutorial.txt gittutorial: wrap literal examples in backticks 2023-04-20 14:34:08 -07:00
gitweb.conf.txt
…
gitweb.txt docs: typofixes 2023-06-12 13:52:51 -07:00
gitworkflows.txt doc: uniformize <URL> placeholders' case 2021-11-09 09:39:11 -08:00
glossary-content.txt glossary: add reachability bitmap description 2022-10-30 19:58:46 -04:00
howto-index.sh
…
i18n.txt
…
install-doc-quick.sh
…
install-webdoc.sh
…
line-range-format.txt
…
line-range-options.txt
…
lint-fsck-msgids.perl Documentation: add lint-fsck-msgids 2022-10-25 15:44:19 -07:00
lint-gitlink.perl doc lint: make "lint-docs" non-.PHONY 2021-10-15 10:29:11 -07:00
lint-man-end-blurb.perl doc lint: emit errors on STDERR 2021-10-15 10:16:57 -07:00
lint-man-section-order.perl git docs: add a category for file formats, protocols and interfaces 2022-08-04 14:12:23 -07:00
manpage-bold-literal.xsl
…
manpage-normal.xsl Merge branch 'fc/doc-man-lift-title-length-limit' 2023-05-10 10:23:29 -07:00
manpage.xsl
…
merge-options.txt Document positive variant of commit and merge option "--no-verify" 2021-10-29 11:22:56 -07:00
merge-strategies.txt
…
object-format-disclaimer.txt doc: sha256 is no longer experimental 2023-07-31 09:11:04 -07:00
pretty-formats.txt doc: pretty-formats note wide char limitations, and add tests 2023-01-19 14:35:15 -08:00
pretty-options.txt log: document --encoding behavior on iconv() failure 2021-10-29 14:35:59 -07:00
pull-fetch-param.txt
…
ref-reachability-filters.txt
…
rerere-options.txt doc: clarify rerere-autoupdate 2022-08-03 13:57:25 -07:00
rev-list-description.txt
…
rev-list-options.txt rev-list-options: fix typo in `--stdin` documentation 2023-08-16 11:42:54 -07:00
revisions.txt Documentation: document AUTO_MERGE 2023-05-23 17:21:47 +09:00
scalar.txt scalar: include in standard Git build & installation 2022-09-02 10:02:55 -07:00
sequencer.txt
…
signoff-option.txt
…
texi.xsl
…
trace2-target-values.txt
…
transfer-data-leaks.txt
…
urls-remotes.txt docs: typofixes 2023-06-12 13:52:51 -07:00
urls.txt
…
user-manual.conf
…
user-manual.txt cache.h: remove this no-longer-used header 2023-06-21 13:39:53 -07:00