kernel
/
git
mirror of https://git.kernel.org/pub/scm/git/git.git
1
0
Fork 0
Code Releases Activity

Merge branch 'kj/my-first-contribution-updates' 

Doc updates.

* kj/my-first-contribution-updates:
  docs: replace git_config to repo_config
  docs: clarify cmd_psuh signature and explain UNUSED macro
  docs: remove unused mentoring mailing list reference
maint
Junio C Hamano 2025-05-27 13:59:12 -07:00
parent 21b0eb0b6a 7649d316ce
commit e8f4e146d4
1 changed files with 33 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
Documentation/MyFirstContribution.adoc
View File

@ -40,14 +40,6 @@ the list by sending an email to <git+subscribe@vger.kernel.org>
The https://lore.kernel.org/git[archive] of this mailing list is
available to view in a browser.

==== https://groups.google.com/forum/#!forum/git-mentoring[git-mentoring@googlegroups.com]

This mailing list is targeted to new contributors and was created as a place to
post questions and receive answers outside of the public eye of the main list.
Veteran contributors who are especially interested in helping mentor newcomers
are present on the list. In order to avoid search indexers, group membership is
required to view messages; anyone can join and no approval is required.

==== https://web.libera.chat/#git-devel[#git-devel] on Libera Chat

This IRC channel is for conversations between Git contributors. If someone is
@ -150,15 +142,31 @@ 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)
int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
const char *prefix UNUSED, struct repository *repo UNUSED)
----

A few things to note:

* A subcommand implementation takes its command line arguments
in `int argc` + `const char **argv`, like `main()` would.

* It also takes two extra parameters, `prefix` and `repo`. What
they mean will not be discussed until much later.

* Because this first example will not use any of the parameters,
your compiler will give warnings on unused parameters. As the
list of these four parameters is mandated by the API to add
new built-in commands, you cannot omit them. Instead, you add
`UNUSED` to each of them to tell the compiler that you *know*
you are not (yet) using it.

We'll also need to add the declaration of psuh; open up `builtin.h`, find the
declaration for `cmd_pull`, and add a new line for `psuh` immediately before it,
in order to keep the declarations alphabetically sorted:

----
int cmd_psuh(int argc, const char **argv, const char *prefix);
int cmd_psuh(int argc, const char **argv, const char *prefix, struct repository *repo);
----

Be sure to `#include "builtin.h"` in your `psuh.c`. You'll also need to
@ -174,7 +182,8 @@ 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)
int cmd_psuh(int argc UNUSED, const char **argv UNUSED,
const char *prefix UNUSED, struct repository *repo UNUSED)
{
printf(_("Pony saying hello goes here.\n"));
return 0;
@ -287,8 +296,9 @@ on the reference implementation linked at the top of this document.
It's probably useful to do at least something besides printing out a string.
Let's start by having a look at everything we get.

Modify your `cmd_psuh` implementation to dump the args you're passed, keeping
existing `printf()` calls in place:
Modify your `cmd_psuh` implementation to dump the args you're passed,
keeping existing `printf()` calls in place; because the args are now
used, remove the `UNUSED` macro from them:

----
int i;
@ -312,7 +322,8 @@ on the command line, including the name of our command. (If `prefix` is empty
for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so
helpful. So what other context can we get?

Add a line to `#include "config.h"`. Then, add the following bits to the
Add a line to `#include "config.h"` and `#include "repository.h"`.
Then, add the following bits to the function body:
function body:

----
@ -320,18 +331,18 @@ function body:

...

git_config(git_default_config, NULL);
if (git_config_get_string_tmp("user.name", &cfg_name) > 0)
repo_config(repo, git_default_config, NULL);
if (repo_config_get_string_tmp(repo, "user.name", &cfg_name))
printf(_("No name is found in config\n"));
else
printf(_("Your name: %s\n"), cfg_name);
----

`git_config()` will grab the configuration from config files known to Git and
apply standard precedence rules. `git_config_get_string_tmp()` will look up
`repo_config()` will grab the configuration from config files known to Git and
apply standard precedence rules. `repo_config_get_string_tmp()` will look up
a specific key ("user.name") and give you the value. There are a number of
single-key lookup functions like this one; you can see them all (and more info
about how to use `git_config()`) in `Documentation/technical/api-config.adoc`.
about how to use `repo_config()`) in `Documentation/technical/api-config.adoc`.

You should see that the name printed matches the one you see when you run:

@ -364,7 +375,7 @@ status_init_config(&s, git_status_config);
----

But as we drill down, we can find that `status_init_config()` wraps a call
to `git_config()`. Let's modify the code we wrote in the previous commit.
to `repo_config()`. Let's modify the code we wrote in the previous commit.

Be sure to include the header to allow you to use `struct wt_status`:

@ -380,8 +391,8 @@ prepare it, and print its contents:

...

wt_status_prepare(the_repository, &status);
git_config(git_default_config, &status);
wt_status_prepare(repo, &status);
repo_config(repo, git_default_config, &status);

...