Re: [PATCH 3/4] Docs: Add cmd_psuh with repo and UNUSED removal

[Emily Shaffer <nasamuffin@google.com>]

On Wed, Apr 16, 2025 at 11:44:49AM +0530, K Jayatheerth wrote:
> 
> This commit improves the `cmd_psuh` documentation example by:
> 
> Correcting the function signature to include struct repository *repo.
> Makes the signature accurate and consistent with typical Git built-in
> commands.
> 
> Removing the `UNUSED` macros from the `cmd_psuh` function arguments
> (argc, argv, prefix, repo). This is done because the example now
> uses these arguments.
> 
> Showing how to access the repository's Git directory (repo->gitdir)
> within the cmd_psuh function. This provides a practical example of
> how to use the repo argument and repository-related information.
> 
> Keeps your existing printf() calls in place.
> This lets the users see the arguments which is given to the function.
> 
> This enhanced example provides a more complete illustration of
> Adding a Git built-in command and use the repository argument.

As I said for the prior patch, please revise the commit message; we
don't need the line by line description of what you're doing in the diff
below as we can read the diff :)

The important part is pointing out that the codebase has moved on to
require UNUSED and passing around a repository object, and that it's
interesting for newbies to see what's inside of `repo` in this learning
exercise.

> 
> Signed-off-by: K Jayatheerth <jayatheerthkulkarni2005@gmail.com>
> ---
>  Documentation/MyFirstContribution.adoc | 19 ++++++++++++++++---
>  1 file changed, 16 insertions(+), 3 deletions(-)
> 
> diff --git a/Documentation/MyFirstContribution.adoc b/Documentation/MyFirstContribution.adoc
> index b463d42f63..ed6dcc1fc6 100644
> --- a/Documentation/MyFirstContribution.adoc
> +++ b/Documentation/MyFirstContribution.adoc
> @@ -158,7 +158,7 @@ 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 +174,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,10 +288,14 @@ 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
> +Modify your `cmd_psuh` implementation to dump the args you're passed
> +and removing the UNUSED macro from them, keeping

"Modify ... and removing" mixes up tenses. Better to say,

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:

>  existing `printf()` calls in place:
>  
>  ----
> +int cmd_psuh(int argc, const char **argv, 
> +			const char *prefix, struct repository *repo)
> +{
>  	int i;
>  
>  	...
> @@ -305,6 +310,14 @@ existing `printf()` calls in place:
>  	printf(_("Your current working directory:\n<top-level>%s%s\n"),
>  	       prefix ? "/" : "", prefix ? prefix : "");
>  
> +	if (repo && repo->gitdir) {
> +        printf(_("Git directory: %s\n"), repo->gitdir);
> +    } else {
> +        printf(_("No Git directory found.\n"));
> +    }

Your whitespace is wonky here, Git uses tabs, not spaces. Double check
it, please :)

> +
> +	...
> +}
>  ----
>  
>  Build and try it. As you may expect, there's pretty much just whatever we give
> -- 
> 2.49.GIT
> 
>