From mboxrd@z Thu Jan 1 00:00:00 1970 From: Michael J Gruber Subject: [RFD/PATCH] Documentation: mention category Date: Tue, 9 Dec 2014 12:21:02 +0100 Message-ID: <538d1a10bda3793ea10ec6f7de43de371d17e709.1418123780.git.git@drmicha.warpmail.net> To: git@vger.kernel.org X-From: git-owner@vger.kernel.org Tue Dec 09 12:21:16 2014 Return-path: Envelope-to: gcvg-git-2@plane.gmane.org Received: from vger.kernel.org ([209.132.180.67]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1XyIqw-00068r-Hb for gcvg-git-2@plane.gmane.org; Tue, 09 Dec 2014 12:21:15 +0100 Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1756642AbaLILVJ (ORCPT ); Tue, 9 Dec 2014 06:21:09 -0500 Received: from out3-smtp.messagingengine.com ([66.111.4.27]:40995 "EHLO out3-smtp.messagingengine.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1754732AbaLILVE (ORCPT ); Tue, 9 Dec 2014 06:21:04 -0500 Received: from compute2.internal (compute2.nyi.internal [10.202.2.42]) by mailout.nyi.internal (Postfix) with ESMTP id 1E28020A45 for ; Tue, 9 Dec 2014 06:21:04 -0500 (EST) Received: from frontend2 ([10.202.2.161]) by compute2.internal (MEProxy); Tue, 09 Dec 2014 06:21:04 -0500 DKIM-Signature: v=1; a=rsa-sha1; c=relaxed/relaxed; d= messagingengine.com; h=x-sasl-enc:from:to:subject:date :message-id; s=smtpout; bh=srfbifdatJrWUYP0fx5KGse8m/o=; b=OeE95 wGevxLKVBns+uJmC+DFfwA7lsGPghkUVjKKhVU5CsCjCTUI+9e1+VRAAVWrgP+Zo W3ANGK8reCwV2S//xy715JW88z5ai3tOQjFgTIEOWDGHw0s4oKwwUSwbI1nzniAf Xm5GRggtpa9DCVpQ4NIUxa5n1F065CuTZslXYs= X-Sasl-enc: 7WylU7IzIUwRf9wtHaaQTKNd/ZbtpKVzvBIjDsVxUaMB 1418124063 Received: from localhost (unknown [130.75.46.56]) by mail.messagingengine.com (Postfix) with ESMTPA id 5ADE268018D; Tue, 9 Dec 2014 06:21:03 -0500 (EST) X-Mailer: git-send-email 2.2.0.345.g7041aac Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org Archived-At: Quite a few users seem to get confused about which commands to use as the main git interface. While `git --help' gives an overview, users seem to discover commands from the man page which does not tell them to stay away from plumbing commands first. Introduce a category section in each man page which helps users decide whether to read on at all. Signed-off-by: Michael J Gruber --- This is just a suggestion to give new users better orientation. The naming for the categories is up for discussion, of course. The categorization itself is taken from command-list.txt and translated via: --->%--- case "$category" in ancillaryinterrogators*) out="Ancillary interrogator" ;; ancillarymanipulator*) out="Ancillary manipulator" ;; foreignscminterface*) out="Interface to foreign SCM" ;; mainporcelain*) out="Main user interface command (porcelain)" ;; plumbing*) out="Low level command for script writers (plumbing)" ;; purehelpers*) out="Helper command for script writers" ;; sync*) out="Commands used internally for synching repositories" ;; *) out="" echo "What to do with $command - $category" ;; esac ---<%--- Rather than changing git-foo.txt, we could do the substitution magic from Documentation/Makefile, of course, to keep man pages and command-list in sync. Although this would keep me from submitting the final series with 1 patch per file :) Documentation/git-add.txt | 4 ++++ Documentation/git-am.txt | 4 ++++ Documentation/git-annotate.txt | 4 ++++ Documentation/git-apply.txt | 4 ++++ Documentation/git-archimport.txt | 4 ++++ Documentation/git-archive.txt | 4 ++++ Documentation/git-bisect.txt | 4 ++++ Documentation/git-blame.txt | 4 ++++ Documentation/git-branch.txt | 4 ++++ Documentation/git-bundle.txt | 4 ++++ Documentation/git-cat-file.txt | 4 ++++ Documentation/git-check-attr.txt | 4 ++++ Documentation/git-check-ignore.txt | 4 ++++ Documentation/git-check-mailmap.txt | 4 ++++ Documentation/git-check-ref-format.txt | 4 ++++ Documentation/git-checkout-index.txt | 4 ++++ Documentation/git-checkout.txt | 4 ++++ Documentation/git-cherry-pick.txt | 4 ++++ Documentation/git-cherry.txt | 4 ++++ Documentation/git-citool.txt | 4 ++++ Documentation/git-clean.txt | 4 ++++ Documentation/git-clone.txt | 4 ++++ Documentation/git-column.txt | 4 ++++ Documentation/git-commit-tree.txt | 4 ++++ Documentation/git-commit.txt | 4 ++++ Documentation/git-config.txt | 4 ++++ Documentation/git-count-objects.txt | 4 ++++ Documentation/git-credential-cache.txt | 4 ++++ Documentation/git-credential-store.txt | 4 ++++ Documentation/git-credential.txt | 4 ++++ Documentation/git-cvsexportcommit.txt | 4 ++++ Documentation/git-cvsimport.txt | 4 ++++ Documentation/git-cvsserver.txt | 4 ++++ Documentation/git-daemon.txt | 4 ++++ Documentation/git-describe.txt | 4 ++++ Documentation/git-diff-files.txt | 4 ++++ Documentation/git-diff-index.txt | 4 ++++ Documentation/git-diff-tree.txt | 4 ++++ Documentation/git-diff.txt | 4 ++++ Documentation/git-difftool.txt | 4 ++++ Documentation/git-fast-export.txt | 4 ++++ Documentation/git-fast-import.txt | 4 ++++ Documentation/git-fetch-pack.txt | 4 ++++ Documentation/git-fetch.txt | 4 ++++ Documentation/git-filter-branch.txt | 4 ++++ Documentation/git-fmt-merge-msg.txt | 4 ++++ Documentation/git-for-each-ref.txt | 4 ++++ Documentation/git-format-patch.txt | 4 ++++ Documentation/git-fsck.txt | 4 ++++ Documentation/git-gc.txt | 4 ++++ Documentation/git-get-tar-commit-id.txt | 4 ++++ Documentation/git-grep.txt | 4 ++++ Documentation/git-gui.txt | 4 ++++ Documentation/git-hash-object.txt | 4 ++++ Documentation/git-help.txt | 4 ++++ Documentation/git-http-backend.txt | 4 ++++ Documentation/git-http-fetch.txt | 4 ++++ Documentation/git-http-push.txt | 4 ++++ Documentation/git-imap-send.txt | 4 ++++ Documentation/git-index-pack.txt | 4 ++++ Documentation/git-init.txt | 4 ++++ Documentation/git-instaweb.txt | 4 ++++ Documentation/git-interpret-trailers.txt | 4 ++++ Documentation/git-log.txt | 4 ++++ Documentation/git-ls-files.txt | 4 ++++ Documentation/git-ls-remote.txt | 4 ++++ Documentation/git-ls-tree.txt | 4 ++++ Documentation/git-mailinfo.txt | 4 ++++ Documentation/git-mailsplit.txt | 4 ++++ Documentation/git-merge-base.txt | 4 ++++ Documentation/git-merge-file.txt | 4 ++++ Documentation/git-merge-index.txt | 4 ++++ Documentation/git-merge-one-file.txt | 4 ++++ Documentation/git-merge-tree.txt | 4 ++++ Documentation/git-merge.txt | 4 ++++ Documentation/git-mergetool.txt | 4 ++++ Documentation/git-mktag.txt | 4 ++++ Documentation/git-mktree.txt | 4 ++++ Documentation/git-mv.txt | 4 ++++ Documentation/git-name-rev.txt | 4 ++++ Documentation/git-notes.txt | 4 ++++ Documentation/git-p4.txt | 4 ++++ Documentation/git-pack-objects.txt | 4 ++++ Documentation/git-pack-redundant.txt | 4 ++++ Documentation/git-pack-refs.txt | 4 ++++ Documentation/git-parse-remote.txt | 4 ++++ Documentation/git-patch-id.txt | 4 ++++ Documentation/git-prune-packed.txt | 4 ++++ Documentation/git-prune.txt | 4 ++++ Documentation/git-pull.txt | 4 ++++ Documentation/git-push.txt | 4 ++++ Documentation/git-quiltimport.txt | 4 ++++ Documentation/git-read-tree.txt | 4 ++++ Documentation/git-rebase.txt | 4 ++++ Documentation/git-receive-pack.txt | 4 ++++ Documentation/git-reflog.txt | 4 ++++ Documentation/git-relink.txt | 4 ++++ Documentation/git-remote.txt | 4 ++++ Documentation/git-repack.txt | 4 ++++ Documentation/git-replace.txt | 4 ++++ Documentation/git-request-pull.txt | 4 ++++ Documentation/git-rerere.txt | 4 ++++ Documentation/git-reset.txt | 4 ++++ Documentation/git-rev-list.txt | 4 ++++ Documentation/git-rev-parse.txt | 4 ++++ Documentation/git-revert.txt | 4 ++++ Documentation/git-rm.txt | 4 ++++ Documentation/git-send-email.txt | 4 ++++ Documentation/git-send-pack.txt | 4 ++++ Documentation/git-sh-i18n.txt | 4 ++++ Documentation/git-sh-setup.txt | 4 ++++ Documentation/git-shell.txt | 4 ++++ Documentation/git-shortlog.txt | 4 ++++ Documentation/git-show-branch.txt | 4 ++++ Documentation/git-show-index.txt | 4 ++++ Documentation/git-show-ref.txt | 4 ++++ Documentation/git-show.txt | 4 ++++ Documentation/git-stash.txt | 4 ++++ Documentation/git-status.txt | 4 ++++ Documentation/git-stripspace.txt | 4 ++++ Documentation/git-submodule.txt | 4 ++++ Documentation/git-svn.txt | 4 ++++ Documentation/git-symbolic-ref.txt | 4 ++++ Documentation/git-tag.txt | 4 ++++ Documentation/git-unpack-file.txt | 4 ++++ Documentation/git-unpack-objects.txt | 4 ++++ Documentation/git-update-index.txt | 4 ++++ Documentation/git-update-ref.txt | 4 ++++ Documentation/git-update-server-info.txt | 4 ++++ Documentation/git-upload-archive.txt | 4 ++++ Documentation/git-upload-pack.txt | 4 ++++ Documentation/git-var.txt | 4 ++++ Documentation/git-verify-commit.txt | 4 ++++ Documentation/git-verify-pack.txt | 4 ++++ Documentation/git-verify-tag.txt | 4 ++++ Documentation/git-whatchanged.txt | 4 ++++ Documentation/git-write-tree.txt | 4 ++++ Documentation/gitk.txt | 4 ++++ Documentation/gitweb.txt | 4 ++++ 139 files changed, 556 insertions(+) diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt index 9631526..b6a8bc6 100644 --- a/Documentation/git-add.txt +++ b/Documentation/git-add.txt @@ -13,6 +13,10 @@ SYNOPSIS [--intent-to-add | -N] [--refresh] [--ignore-errors] [--ignore-missing] [--] [...] +CATEGORY +-------- +Main user interface command (porcelain) + DESCRIPTION ----------- This command updates the index using the current content found in diff --git a/Documentation/git-am.txt b/Documentation/git-am.txt index 9adce37..b2bbe77 100644 --- a/Documentation/git-am.txt +++ b/Documentation/git-am.txt @@ -18,6 +18,10 @@ SYNOPSIS [( | )...] 'git am' (--continue | --skip | --abort) +CATEGORY +-------- +Main user interface command (porcelain) + DESCRIPTION ----------- Splits mail messages in a mailbox into commit log message, diff --git a/Documentation/git-annotate.txt b/Documentation/git-annotate.txt index 05fd482..f787838 100644 --- a/Documentation/git-annotate.txt +++ b/Documentation/git-annotate.txt @@ -10,6 +10,10 @@ SYNOPSIS [verse] 'git annotate' [options] file [revision] +CATEGORY +-------- +Ancillary interrogator + DESCRIPTION ----------- Annotates each line in the given file with information from the commit diff --git a/Documentation/git-apply.txt b/Documentation/git-apply.txt index f605327..5eab3fa 100644 --- a/Documentation/git-apply.txt +++ b/Documentation/git-apply.txt @@ -18,6 +18,10 @@ SYNOPSIS [--exclude=] [--include=] [--directory=] [--verbose] [...] +CATEGORY +-------- +Low level command for script writers (plumbing) + DESCRIPTION ----------- Reads the supplied diff output (i.e. "a patch") and applies it to files. diff --git a/Documentation/git-archimport.txt b/Documentation/git-archimport.txt index 163b9f6..604b3ff 100644 --- a/Documentation/git-archimport.txt +++ b/Documentation/git-archimport.txt @@ -12,6 +12,10 @@ SYNOPSIS 'git archimport' [-h] [-v] [-o] [-a] [-f] [-T] [-D depth] [-t tempdir] [:] ... +CATEGORY +-------- +Interface to foreign SCM + DESCRIPTION ----------- Imports a project from one or more Arch repositories. It will follow branches diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index cfa1e4e..b286d3e 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -14,6 +14,10 @@ SYNOPSIS [--remote= [--exec=]] [...] +CATEGORY +-------- +Main user interface command (porcelain) + DESCRIPTION ----------- Creates an archive of the specified format containing the tree diff --git a/Documentation/git-bisect.txt b/Documentation/git-bisect.txt index 4cb52a7..79e4526 100644 --- a/Documentation/git-bisect.txt +++ b/Documentation/git-bisect.txt @@ -11,6 +11,10 @@ SYNOPSIS [verse] 'git bisect' +CATEGORY +-------- +Main user interface command (porcelain) + DESCRIPTION ----------- The command takes various subcommands, and different options depending diff --git a/Documentation/git-blame.txt b/Documentation/git-blame.txt index 9f23a86..88c014f 100644 --- a/Documentation/git-blame.txt +++ b/Documentation/git-blame.txt @@ -12,6 +12,10 @@ SYNOPSIS [-L ] [-S ] [-M] [-C] [-C] [-C] [--since=] [--abbrev=] [ | --contents | --reverse ] [--] +CATEGORY +-------- +Ancillary interrogator + DESCRIPTION ----------- diff --git a/Documentation/git-branch.txt b/Documentation/git-branch.txt index 311b336..f751bc9 100644 --- a/Documentation/git-branch.txt +++ b/Documentation/git-branch.txt @@ -19,6 +19,10 @@ SYNOPSIS 'git branch' (-d | -D) [-r] ... 'git branch' --edit-description [] +CATEGORY +-------- +Main user interface command (porcelain) + DESCRIPTION ----------- diff --git a/Documentation/git-bundle.txt b/Documentation/git-bundle.txt index 0417562..21980ae 100644 --- a/Documentation/git-bundle.txt +++ b/Documentation/git-bundle.txt @@ -14,6 +14,10 @@ SYNOPSIS 'git bundle' list-heads [...] 'git bundle' unbundle [...] +CATEGORY +-------- +Main user interface command (porcelain) + DESCRIPTION ----------- diff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt index f6a16f4..9bf2c61 100644 --- a/Documentation/git-cat-file.txt +++ b/Documentation/git-cat-file.txt @@ -12,6 +12,10 @@ SYNOPSIS 'git cat-file' (-t | -s | -e | -p | | --textconv ) 'git cat-file' (--batch | --batch-check) < +CATEGORY +-------- +Low level command for script writers (plumbing) + DESCRIPTION ----------- In its first form, the command provides the content or the type of an object in diff --git a/Documentation/git-check-attr.txt b/Documentation/git-check-attr.txt index 00e2aa2..fe45715 100644 --- a/Documentation/git-check-attr.txt +++ b/Documentation/git-check-attr.txt @@ -12,6 +12,10 @@ SYNOPSIS 'git check-attr' [-a | --all | attr...] [--] pathname... 'git check-attr' --stdin [-z] [-a | --all | attr...] < +CATEGORY +-------- +Helper command for script writers + DESCRIPTION ----------- For every pathname, this command will list if each attribute is 'unspecified', diff --git a/Documentation/git-check-ignore.txt b/Documentation/git-check-ignore.txt index ee2e091..142560b 100644 --- a/Documentation/git-check-ignore.txt +++ b/Documentation/git-check-ignore.txt @@ -12,6 +12,10 @@ SYNOPSIS 'git check-ignore' [options] pathname... 'git check-ignore' [options] --stdin < +CATEGORY +-------- +Helper command for script writers + DESCRIPTION ----------- diff --git a/Documentation/git-check-mailmap.txt b/Documentation/git-check-mailmap.txt index 39028ee..5eb9fc7 100644 --- a/Documentation/git-check-mailmap.txt +++ b/Documentation/git-check-mailmap.txt @@ -12,6 +12,10 @@ SYNOPSIS 'git check-mailmap' [options] ... +CATEGORY +-------- +Helper command for script writers + DESCRIPTION ----------- diff --git a/Documentation/git-check-ref-format.txt b/Documentation/git-check-ref-format.txt index fc02959..4868ccb 100644 --- a/Documentation/git-check-ref-format.txt +++ b/Documentation/git-check-ref-format.txt @@ -13,6 +13,10 @@ SYNOPSIS 'git check-ref-format' --branch +CATEGORY +-------- +Helper command for script writers + DESCRIPTION ----------- Checks if a given 'refname' is acceptable, and exits with a non-zero diff --git a/Documentation/git-checkout-index.txt b/Documentation/git-checkout-index.txt index 4d33e7b..cec0677 100644 --- a/Documentation/git-checkout-index.txt +++ b/Documentation/git-checkout-index.txt @@ -15,6 +15,10 @@ SYNOPSIS [-z] [--stdin] [--] [...] +CATEGORY +-------- +Low level command for script writers (plumbing) + DESCRIPTION ----------- Will copy all files listed from the index to the working directory diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 33ad2ad..69ed9db 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -15,6 +15,10 @@ SYNOPSIS 'git checkout' [-f|--ours|--theirs|-m|--conflict=