fix up example code in MyFirstObjectWalk tutorial

[john-cai]

MyFirstObjectWalk tutorial was missing directives to add some header
files. Also fixes some initialization code.

Changes since v1:

• added back ticks to header file names
• wrapped overly long lines

Changes since v2:

• fixed commit organization

cc: Eric Sunshine sunshine@sunshineco.com

[gitgitgadget]

Welcome to GitGitGadget

Hi @john-cai, and welcome to GitGitGadget, the GitHub App to send patch series to the Git mailing list from GitHub Pull Requests.

Please make sure that your Pull Request has a good description, as it will be used as cover letter.

Also, it is a good idea to review the commit messages one last time, as the Git project expects them in a quite specific form:

• the lines should not exceed 76 columns,
• the first line should be like a header and typically start with a prefix like "tests:" or "revisions:" to state which subsystem the change is about, and
• the commit messages' body should be describing the "why?" of the change.
• Finally, the commit messages should end in a Signed-off-by: line matching the commits' author.

It is in general a good idea to await the automated test ("Checks") in this Pull Request before contributing the patches, e.g. to avoid trivial issues such as unportable code.

Contributing the patches

Before you can contribute the patches, your GitHub username needs to be added to the list of permitted users. Any already-permitted user can do that, by adding a comment to your PR of the form /allow. A good way to find other contributors is to locate recent pull requests where someone has been /allowed:

• Search: is:pr is:open "/allow"

Both the person who commented /allow and the PR author are able to /allow you.

An alternative is the channel #git-devel on the Libera Chat IRC network:

<newcontributor> I've just created my first PR, could someone please /allow me? https://github.com/gitgitgadget/git/pull/12345
<veteran> newcontributor: it is done
<newcontributor> thanks!

Once on the list of permitted usernames, you can contribute the patches to the Git mailing list by adding a PR comment /submit.

If you want to see what email(s) would be sent for a /submit request, add a PR comment /preview to have the email(s) sent to you. You must have a public GitHub email address for this.

After you submit, GitGitGadget will respond with another comment that contains the link to the cover letter mail in the Git mailing list archive. Please make sure to monitor the discussion in that thread and to address comments and suggestions (while the comments and suggestions will be mirrored into the PR by GitGitGadget, you will still want to reply via mail).

If you do not want to subscribe to the Git mailing list just to be able to respond to a mail, you can download the mbox from the Git mailing list archive (click the (raw) link), then import it into your mail program. If you use GMail, you can do this via:

curl -g --user "<EMailAddress>:<Password>" \
    --url "imaps://imap.gmail.com/INBOX" -T /path/to/raw.txt

To iterate on your change, i.e. send a revised patch or patch series, you will first want to (force-)push to the same branch. You probably also want to modify your Pull Request description (or title). It is a good idea to summarize the revision by adding something like this to the cover letter (read: by editing the first comment on the PR, i.e. the PR description):

Changes since v1:
- Fixed a typo in the commit message (found by ...)
- Added a code comment to ... as suggested by ...
...

To send a new iteration, just add another PR comment with the contents: /submit.

Need help?

New contributors who want advice are encouraged to join git-mentoring@googlegroups.com, where volunteers who regularly contribute to Git are willing to answer newbie questions, give advice, or otherwise provide mentoring to interested contributors. You must join in order to post or view messages, but anyone can join.

You may also be able to find help in real time in the developer IRC channel, #git-devel on Libera Chat. Remember that IRC does not support offline messaging, so if you send someone a private message and log out, they cannot respond to you. The scrollback of #git-devel is archived, though.

[gitgitgadget]

There is an issue in commit 13c8383:
Commit not signed off

[Ikke]

/allow

[gitgitgadget]

User john-cai is now allowed to use GitGitGadget.

[john-cai]

/preview

[gitgitgadget]

Preview email sent as pull.1063.git.1634787278370.gitgitgadget@gmail.com

[john-cai]

/submit

[gitgitgadget]

Submitted as pull.1063.git.1635343531.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-1063/john-cai/jc-fix-my-first-object-walk-v1

To fetch this version to local tag pr-1063/john-cai/jc-fix-my-first-object-walk-v1:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-1063/john-cai/jc-fix-my-first-object-walk-v1

[gitgitgadget]

On the Git mailing list, Eric Sunshine wrote (reply to this):

On Wed, Oct 27, 2021 at 10:05 AM John Cai via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> docs: fix places that break compliation in MyFirstObjectWalk

s/compliation/compilation/

> Two errors in the example code caused compilation failures due to
> a missing semi-colon as well as initialization with an empty struct.
> This commit fixes that to make the MyFirstObjectWalk tutorial easier to
> follow.

s/semi-colon/semicolon/ would also be appropriate for the rest of the
project (but not terribly important in a commit message).

> Signed-off-by: John Cai <johncai86@gmail.com>

The patch itself makes perfect sense. Thanks.

[gitgitgadget]

User Eric Sunshine <sunshine@sunshineco.com> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Eric Sunshine wrote (reply to this):

On Wed, Oct 27, 2021 at 10:05 AM John Cai via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> In several places, headers need to be included or else the code won't
> compile. Since this is the first object walk, it would be nice to
> include them in the tutorial to make it easier to follow.
>
> Signed-off-by: John Cai <johncai86@gmail.com>
> ---
> diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
> @@ -57,9 +57,14 @@ command). So we will send our debug output to `trace_printf()` instead. When
>  Add usage text and `-h` handling, like all subcommands should consistently do
> -(our test suite will notice and complain if you fail to do so).
> +(our test suite will notice and complain if you fail to do so). We'll need to include
> +the "parse-options.h" header.

Makes sense, but we should probably typeset these consistently with
backticks rather than double quotes...

> @@ -195,9 +200,13 @@ Similarly to the default values, we don't have anything to do here yet
> -Add a new function to `builtin/walken.c`:
> +Add a new function to `builtin/walken.c`. We'll also need to include the "config.h" header:

... just as `builtin/walken.c` is typeset with backticks (as are other
pathnames in this document).

> @@ -229,8 +238,14 @@ typically done by calling `repo_init_revisions()` with the repository you intend
> -Add the `struct rev_info` and the `repo_init_revisions()` call:
> +Add the `struct rev_info` and the `repo_init_revisions()` call. We'll also need to include
> +the "revision.h" header:

And so on through the remainder of the patch.

Thanks.

[gitgitgadget]

User Eric Sunshine <sunshine@sunshineco.com> has been added to the cc: list.

[gitgitgadget]

On the Git mailing list, Junio C Hamano wrote (reply to this):

"John Cai via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  Add usage text and `-h` handling, like all subcommands should consistently do
> -(our test suite will notice and complain if you fail to do so).
> +(our test suite will notice and complain if you fail to do so). We'll need to include
> +the "parse-options.h" header.

OK, but wrap this overlong line.  All the lines updated by this
patch, except the one in the last hunk, have become overly long.

[jc: cc'ed the primary author of the document to sanity checking]

Thanks.

>  
>  ----
> +#include "parse-options.h"
> +
> +...
> +
>  int cmd_walken(int argc, const char **argv, const char *prefix)
>  {
>  	const char * const walken_usage[] = {
> @@ -195,9 +200,13 @@ Similarly to the default values, we don't have anything to do here yet
>  ourselves; however, we should call `git_default_config()` if we aren't calling
>  any other existing config callbacks.
>  
> -Add a new function to `builtin/walken.c`:
> +Add a new function to `builtin/walken.c`. We'll also need to include the "config.h" header:
>  
>  ----
> +#include "config.h"
> +
> +...
> +
>  static int git_walken_config(const char *var, const char *value, void *cb)
>  {
>  	/*
> @@ -229,8 +238,14 @@ typically done by calling `repo_init_revisions()` with the repository you intend
>  to target, as well as the `prefix` argument of `cmd_walken` and your `rev_info`
>  struct.
>  
> -Add the `struct rev_info` and the `repo_init_revisions()` call:
> +Add the `struct rev_info` and the `repo_init_revisions()` call. We'll also need to include
> +the "revision.h" header:
> +
>  ----
> +#include "revision.h"
> +
> +...
> +
>  int cmd_walken(int argc, const char **argv, const char *prefix)
>  {
>  	/* This can go wherever you like in your declarations.*/
> @@ -624,9 +639,14 @@ static void walken_object_walk(struct rev_info *rev)
>  ----
>  
>  Let's start by calling just the unfiltered walk and reporting our counts.
> -Complete your implementation of `walken_object_walk()`:
> +Complete your implementation of `walken_object_walk()`. We'll also need to
> +include the "list-objects.h" header.
>  
>  ----
> +#include "list-objects.h"
> +
> +...
> +
>  	traverse_commit_list(rev, walken_show_commit, walken_show_object, NULL);
>  
>  	printf("commits %d\nblobs %d\ntags %d\ntrees %d\n", commit_count,

[john-cai]

/submit

[gitgitgadget]

Submitted as pull.1063.v2.git.1635530296.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git pr-1063/john-cai/jc-fix-my-first-object-walk-v2

To fetch this version to local tag pr-1063/john-cai/jc-fix-my-first-object-walk-v2:

git fetch --no-tags https://github.com/gitgitgadget/git tag pr-1063/john-cai/jc-fix-my-first-object-walk-v2

[gitgitgadget]

On the Git mailing list, Eric Sunshine wrote (reply to this):

On Fri, Oct 29, 2021 at 1:58 PM John Cai via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> Two errors in the example code caused compilation failures due to
> a missing semicolon as well as initialization with an empty struct.
> This commit fixes that to make the MyFirstObjectWalk tutorial easier to
> follow.
>
> Signed-off-by: John Cai <johncai86@gmail.com>
> ---
> diff --git a/Documentation/MyFirstObjectWalk.txt b/Documentation/MyFirstObjectWalk.txt
> @@ -58,6 +58,7 @@ running, enable trace output by setting the environment variable `GIT_TRACE`.
>  Add usage text and `-h` handling, like all subcommands should consistently do
>  (our test suite will notice and complain if you fail to do so).
> +We'll need to include the `parse-options.h` header.

It seems like this change belongs in patch [2/2].

> @@ -65,7 +66,7 @@ int cmd_walken(int argc, const char **argv, const char *prefix)
>         const char * const walken_usage[] = {
>                 N_("git walken"),
>                 NULL,
> -       }
> +       };

Whereas, this change correctly resides in patch [1/2].

>         struct option options[] = {
>                 OPT_END()
>         };
> @@ -195,7 +196,8 @@ Similarly to the default values, we don't have anything to do here yet
>  ourselves; however, we should call `git_default_config()` if we aren't calling
>  any other existing config callbacks.
>
> -Add a new function to `builtin/walken.c`:
> +Add a new function to `builtin/walken.c`.
> +We'll also need to include the `config.h` header:

Should be in patch [2/2].

> @@ -229,7 +231,9 @@ typically done by calling `repo_init_revisions()` with the repository you intend
>  to target, as well as the `prefix` argument of `cmd_walken` and your `rev_info`
>  struct.
>
> -Add the `struct rev_info` and the `repo_init_revisions()` call:
> +Add the `struct rev_info` and the `repo_init_revisions()` call.
> +We'll also need to include the `revision.h` header:

Patch [2/2].

> @@ -624,7 +628,8 @@ static void walken_object_walk(struct rev_info *rev)
>  Let's start by calling just the unfiltered walk and reporting our counts.
> -Complete your implementation of `walken_object_walk()`:
> +Complete your implementation of `walken_object_walk()`.
> +We'll also need to include the `list-objects.h` header.

Also patch [2/2].

> @@ -697,7 +702,7 @@ First, we'll need to `#include "list-objects-filter-options.h"` and set up the
>  static void walken_object_walk(struct rev_info *rev)
>  {
> -       struct list_objects_filter_options filter_options = {};
> +       struct list_objects_filter_options filter_options = { 0 };

Good, this change belongs here in patch [1/2].

[john-cai]

/preview

[gitgitgadget]

This patch series was integrated into seen via git@7fa2d61.

[gitgitgadget]

This patch series was integrated into seen via git@5cdd9e0.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch jc/fix-first-object-walk on the Git mailing list:

Doc update.

Will merge to 'next'?

[gitgitgadget]

This patch series was integrated into seen via git@113b16f.

[gitgitgadget]

This patch series was integrated into seen via git@83edef6.

[gitgitgadget]

This patch series was integrated into seen via git@0015c4b.

[gitgitgadget]

This patch series was integrated into seen via git@44a8058.

[gitgitgadget]

This patch series was integrated into seen via git@d1b7fa7.

[gitgitgadget]

This patch series was integrated into seen via git@261bf12.

[gitgitgadget]

This patch series was integrated into seen via git@7953802.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch jc/fix-first-object-walk on the Git mailing list:

Doc update.

Will merge to 'next'.

[gitgitgadget]

This patch series was integrated into seen via git@3f5e8e5.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch jc/fix-first-object-walk on the Git mailing list:

Doc update.

Will merge to 'next'.

[gitgitgadget]

This patch series was integrated into seen via git@5ca9c29.

[gitgitgadget]

This patch series was integrated into seen via git@e9b8a12.

[gitgitgadget]

This patch series was integrated into next via git@43a5c1e.

[gitgitgadget]

This patch series was integrated into seen via git@c6f1dc5.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch jc/fix-first-object-walk on the Git mailing list:

Doc update.

Will merge to 'master'.
source: <pull.1063.v3.git.1635537163.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@fbd370a.

[gitgitgadget]

This patch series was integrated into seen via git@95375b0.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch jc/fix-first-object-walk on the Git mailing list:

Doc update.

Will merge to 'master'.
source: <pull.1063.v3.git.1635537163.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@8ca859b.

[gitgitgadget]

There was a status update in the "Graduated to 'master'" section about the branch jc/fix-first-object-walk on the Git mailing list:

Doc update.
source: <pull.1063.v3.git.1635537163.gitgitgadget@gmail.com>

[gitgitgadget]

This patch series was integrated into seen via git@3d2dce1.

[gitgitgadget]

This patch series was integrated into next via git@3d2dce1.

[gitgitgadget]

This patch series was integrated into master via git@3d2dce1.

[gitgitgadget]

Closed via 3d2dce1.