git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Emily Shaffer <emilyshaffer@google.com>
To: git@vger.kernel.org
Cc: Emily Shaffer <emilyshaffer@google.com>
Subject: [PATCH 1/3] myfirstcontrib: add 'psuh' to command-list.txt
Date: Fri, 25 Oct 2019 17:51:57 -0700	[thread overview]
Message-ID: <20191026005159.98405-2-emilyshaffer@google.com> (raw)
In-Reply-To: <20191026005159.98405-1-emilyshaffer@google.com>

Users can discover commands and their brief usage by running 'git help
git' or 'git help -a'; both of these pages list all available commands
based on the contents of 'command-list.txt'. That means adding a new
command there is an important part of the new command process, and
therefore belongs in the new command tutorial.

Teach new users how to add their command, and include a brief overview
of how to discover which attributes to place on the command in the list.

Since 'git psuh' prints some workspace info, doesn't modify anything,
and is targeted as a user-facing porcelain command, list it as a
'mainporcelain' and 'info' command.

As the usage string is required to generate this documentation, don't
add the command to the list until after the usage string is added to the
tutorial.

Signed-off-by: Emily Shaffer <emilyshaffer@google.com>
---
 Documentation/MyFirstContribution.txt | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/Documentation/MyFirstContribution.txt b/Documentation/MyFirstContribution.txt
index 5e9b808f5f..12b7256454 100644
--- a/Documentation/MyFirstContribution.txt
+++ b/Documentation/MyFirstContribution.txt
@@ -534,6 +534,28 @@ you want to pass as a parameter something which would usually be interpreted as
 a flag.) `parse_options()` will terminate parsing when it reaches `--` and give
 you the rest of the options afterwards, untouched.
 
+Now that you have a usage hint, you can teach Git how to show it in the general
+command list shown by `git help git` or `git help -a`, which is generated from
+`command-list.txt`. Find the line for 'git-pull' so you can add your 'git-psuh'
+line above it in alphabetical order. Now, we can add some attributes about the
+command which impacts where it shows up in the aforementioned help commands. The
+top of `command-list.txt` shares some information about what each attribute
+means; in those help pages, the commands are sorted according to these
+attributes. `git psuh` is user-facing, or porcelain - so we will mark it as
+"mainporcelain". For "mainporcelain" commands, the comments at the top of
+`command-list.txt` indicate we can also optionally add an attribute from another
+list; since `git psuh` shows some information about the user's workspace but
+doesn't modify anything, let's mark it as "info". Make sure to keep your
+attributes in the same style as the rest of `command-list.txt` using spaces to
+align and delineate them:
+
+----
+git-prune-packed                        plumbingmanipulators
+git-psuh                                mainporcelain		info
+git-pull                                mainporcelain           remote
+git-push                                mainporcelain           remote
+----
+
 Build again. Now, when you run with `-h`, you should see your usage printed and
 your command terminated before anything else interesting happens. Great!
 
-- 
2.24.0.rc0.303.g954a862665-goog


  reply	other threads:[~2019-10-26  0:54 UTC|newest]

Thread overview: 20+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-10-26  0:51 [PATCH 0/3] some clarifications to MyFirstContribution Emily Shaffer
2019-10-26  0:51 ` Emily Shaffer [this message]
2019-10-26  1:08   ` [PATCH 1/3] myfirstcontrib: add 'psuh' to command-list.txt Jonathan Nieder
2019-10-26  8:00     ` SZEDER Gábor
2019-10-28  1:24       ` Junio C Hamano
2019-10-28 11:25         ` SZEDER Gábor
2019-10-29 20:39       ` Johannes Schindelin
2019-10-26  0:51 ` [PATCH 2/3] myfirstcontrib: add dependency installation step Emily Shaffer
2019-10-26  1:12   ` Jonathan Nieder
2019-10-28  1:27     ` Junio C Hamano
2019-10-31 20:58       ` Emily Shaffer
2019-10-26  0:51 ` [PATCH 3/3] myfirstcontrib: hint to find gitgitgadget allower Emily Shaffer
2019-10-26  1:15   ` Jonathan Nieder
2019-10-29 20:43     ` Johannes Schindelin
2019-10-27  1:39   ` Pratyush Yadav
2019-10-26  1:17 ` [PATCH 0/3] some clarifications to MyFirstContribution Jonathan Nieder
2019-10-31 21:03 ` [PATCH v2 " Emily Shaffer
2019-10-31 21:03   ` [PATCH v2 1/3] myfirstcontrib: add 'psuh' to command-list.txt Emily Shaffer
2019-10-31 21:03   ` [PATCH v2 2/3] myfirstcontrib: add dependency installation step Emily Shaffer
2019-10-31 21:03   ` [PATCH v2 3/3] myfirstcontrib: hint to find gitgitgadget allower Emily Shaffer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20191026005159.98405-2-emilyshaffer@google.com \
    --to=emilyshaffer@google.com \
    --cc=git@vger.kernel.org \
    --subject='Re: [PATCH 1/3] myfirstcontrib: add '\''psuh'\'' to command-list.txt' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).