From: "SZEDER Gábor" <szeder.dev@gmail.com>
To: Emily Shaffer <emilyshaffer@google.com>
Cc: git@vger.kernel.org,
Johannes Schindelin <johannes.schindelin@gmx.de>,
Jonathan Tan <jonathantanmy@google.com>
Subject: Re: [PATCH v6 1/2] documentation: add tutorial for first contribution
Date: Fri, 18 Oct 2019 18:40:27 +0200 [thread overview]
Message-ID: <20191018164027.GI29845@szeder.dev> (raw)
In-Reply-To: <20190517190701.49722-2-emilyshaffer@google.com>
On Fri, May 17, 2019 at 12:07:02PM -0700, Emily Shaffer wrote:
> +=== Adding a New Command
> +
> +Lots of the subcommands are written as builtins, which means they are
> +implemented in C and compiled into the main `git` executable. Implementing the
> +very simple `psuh` command as a built-in will demonstrate the structure of the
> +codebase, the internal API, and the process of working together as a contributor
> +with the reviewers and maintainer to integrate this change into the system.
> +
> +Built-in subcommands are typically implemented in a function named "cmd_"
> +followed by the name of the subcommand, in a source file named after the
> +subcommand and contained within `builtin/`. So it makes sense to implement your
> +command in `builtin/psuh.c`. Create that file, and within it, write the entry
> +point for your command in a function matching the style and signature:
> +
> +----
> +int cmd_psuh(int argc, const char **argv, const char *prefix)
> +----
> +
> +We'll also need to add the declaration of psuh; open up `builtin.h`, find the
> +declaration for `cmd_push`, and add a new line for `psuh` immediately before it,
> +in order to keep the declarations sorted:
> +
> +----
> +int cmd_psuh(int argc, const char **argv, const char *prefix);
> +----
> +
> +Be sure to `#include "builtin.h"` in your `psuh.c`.
> +
> +Go ahead and add some throwaway printf to that function. This is a decent
> +starting point as we can now add build rules and register the command.
> +
> +NOTE: Your throwaway text, as well as much of the text you will be adding over
> +the course of this tutorial, is user-facing. That means it needs to be
> +localizable. Take a look at `po/README` under "Marking strings for translation".
> +Throughout the tutorial, we will mark strings for translation as necessary; you
> +should also do so when writing your user-facing commands in the future.
> +
> +----
> +int cmd_psuh(int argc, const char **argv, const char *prefix)
> +{
> + printf(_("Pony saying hello goes here.\n"));
> + return 0;
> +}
> +----
> +
> +Let's try to build it. Open `Makefile`, find where `builtin/push.o` is added
> +to `BUILTIN_OBJS`, and add `builtin/psuh.o` in the same way next to it in
> +alphabetical order. Once you've done so, move to the top-level directory and
> +build simply with `make`. Also add the `DEVELOPER=1` variable to turn on
> +some additional warnings:
> +
> +----
> +$ echo DEVELOPER=1 >config.mak
> +$ make
> +----
> +
> +NOTE: When you are developing the Git project, it's preferred that you use the
> +`DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn
> +it off, but it's a good idea to mention the problem to the mailing list.
> +
> +NOTE: The Git build is parallelizable. `-j#` is not included above but you can
> +use it as you prefer, here and elsewhere.
> +
> +Great, now your new command builds happily on its own. But nobody invokes it.
> +Let's change that.
> +
> +The list of commands lives in `git.c`. We can register a new command by adding
> +a `cmd_struct` to the `commands[]` array. `struct cmd_struct` takes a string
> +with the command name, a function pointer to the command implementation, and a
> +setup option flag. For now, let's keep mimicking `push`. Find the line where
> +`cmd_push` is registered, copy it, and modify it for `cmd_psuh`, placing the new
> +line in alphabetical order.
> +
> +The options are documented in `builtin.h` under "Adding a new built-in." Since
> +we hope to print some data about the user's current workspace context later,
> +we need a Git directory, so choose `RUN_SETUP` as your only option.
Just leaving a quick note here: an entry about the new command should
be added to 'command-list.txt' as well, so it will be included in the
list of available commands in 'git help -a' or even in 'git help'
and in completion, if the command is marked with the necessary
attributes.
next prev parent reply other threads:[~2019-10-18 16:40 UTC|newest]
Thread overview: 44+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-04-11 18:32 [PATCH 0/1] documentation: add lab for first contribution Emily Shaffer via GitGitGadget
2019-04-11 18:32 ` [PATCH 1/1] " Emily Shaffer via GitGitGadget
2019-04-12 3:20 ` Junio C Hamano
2019-04-12 22:03 ` Emily Shaffer
2019-04-13 5:39 ` Junio C Hamano
2019-04-15 17:26 ` Emily Shaffer
2019-04-11 21:03 ` [PATCH 0/1] " Josh Steadmon
2019-04-12 2:35 ` Junio C Hamano
2019-04-12 22:58 ` Emily Shaffer
2019-04-16 20:26 ` [PATCH v2 " Emily Shaffer via GitGitGadget
2019-04-16 20:26 ` [PATCH v2 1/1] " Emily Shaffer via GitGitGadget
2019-04-17 5:32 ` Junio C Hamano
2019-04-17 8:07 ` Eric Sunshine
2019-04-18 0:05 ` Junio C Hamano
2019-04-17 23:16 ` Emily Shaffer
2019-04-16 21:13 ` [PATCH v2 0/1] " Emily Shaffer
2019-04-19 16:57 ` [PATCH v3] " Emily Shaffer
2019-04-21 10:52 ` Junio C Hamano
2019-04-22 22:27 ` Emily Shaffer
2019-04-23 19:34 ` [PATCH v4] documentation: add tutorial " Emily Shaffer
2019-04-30 18:59 ` Josh Steadmon
2019-05-02 0:57 ` Emily Shaffer
2019-05-03 2:11 ` Phil Hord
2019-05-07 19:05 ` Emily Shaffer
2019-05-06 22:28 ` Jonathan Tan
2019-05-07 19:59 ` Emily Shaffer
2019-05-07 20:32 ` Jonathan Tan
2019-05-08 2:45 ` Junio C Hamano
2019-05-07 21:30 ` [PATCH v5 0/2] documentation: add lab " Emily Shaffer
2019-05-07 21:30 ` [PATCH v5 1/2] documentation: add tutorial " Emily Shaffer
2019-05-07 23:25 ` Emily Shaffer
2019-05-08 3:46 ` Junio C Hamano
2019-05-08 18:58 ` Emily Shaffer
2019-05-08 19:53 ` Jonathan Tan
2019-05-07 21:30 ` [PATCH v5 2/2] documentation: add anchors to MyFirstContribution Emily Shaffer
2019-05-08 3:30 ` [PATCH v5 0/2] documentation: add lab for first contribution Junio C Hamano
2019-05-17 19:03 ` [PATCH v6 0/2] documentation: add tutorial " Emily Shaffer
2019-05-17 19:07 ` [PATCH v6 1/2] " Emily Shaffer
2019-05-26 7:48 ` Christian Couder
2019-05-29 20:09 ` Emily Shaffer
2019-10-18 16:40 ` SZEDER Gábor [this message]
2019-10-18 22:54 ` Emily Shaffer
2019-05-17 19:07 ` [PATCH v6 2/2] documentation: add anchors to MyFirstContribution Emily Shaffer
2019-05-29 20:18 ` [PATCH] doc: add some nit fixes " 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
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20191018164027.GI29845@szeder.dev \
--to=szeder.dev@gmail.com \
--cc=emilyshaffer@google.com \
--cc=git@vger.kernel.org \
--cc=johannes.schindelin@gmx.de \
--cc=jonathantanmy@google.com \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
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 read-only IMAP folder(s) and NNTP newsgroup(s).