Add a checkout example by tiennou · Pull Request #4692 · libgit2/libgit2

tiennou · 2018-06-23T13:51:58Z

This adds an example on how to perform checkouts with libgit2.

Note that it only does the "branch moving" part of checkout, so no git checkout src/file.c.

tiennou · 2018-06-23T14:01:07Z

Note that while working with refishs, I've grown to like git_annotated_commit for its ability to abstract away the details (like the automated reflog messages).

And looking around its API, it might be worthwhile to add a git_repository_set_head_from_annotated, that would underlie all others set_heads we have. Also, I was a little confused that all the "virtual commits" creation lies in "merge.c", so maybe moving that back to "annotated.c" so the separation is cleaner ?

pks-t

Thanks for this example, @tiennou.

While there's a lot of comments, I guess most of them are fast to address. One thing I'd like to see though is to have a lot more /** */-style documentation. The examples are being parsed and presented on Doxygen to serve as some kind of walkthrough with explanations, so that would benefit users a lot, I guess. It's not a requirement to get this merged, though.

pks-t · 2018-06-29T12:57:01Z

+#	define PRIdZ "zd"
+#endif
+
+/** The following example demonstrates how to do checkouts with libgit2.


Nit: multiline-comments usually start with an empty /** line

pks-t · 2018-06-29T12:57:54Z

+/** The following example demonstrates how to do checkouts with libgit2.
+ *
+ * Recognized options are :
+ *  --force: don't actually commit the merge.


This comment looks like a copy-paste error?

pks-t · 2018-06-29T12:58:20Z

+
+static void print_usage(void)
+{
+	fprintf(stderr, "usage: checkout [--force] <branch>\n");


You're missing the other options

pks-t · 2018-06-29T13:01:30Z

+static void print_checkout_progress(const char *path, size_t completed_steps, size_t total_steps, void *payload)
+{
+	(void)payload;
+	printf("checkout: %s %" PRIuZ "/%" PRIuZ "\n", path, completed_steps, total_steps);


Usually you'd have to first erase the previous line and write on that same line again. But for a simple example this is sufficient, I guess

pks-t · 2018-06-29T13:02:10Z

+	}
+
+
+


A few blank lines too much

pks-t · 2018-06-29T13:09:29Z

+
+	parse_options(&path, &opts, &args);
+
+	git_libgit2_init();


You need to check the return value of that function.

pks-t · 2018-06-29T13:10:27Z

+		fprintf(stderr, "missing argument\n");
+		err = -1;
+		goto cleanup;
+	}


This check looks like it belongs to parse_opts, as well

pks-t · 2018-06-29T13:11:34Z

+		err = perform_checkout_ref(repo, checkout_target, &opts);
+	} else {
+		printf("failed to resolve %s: %s\n", args.argv[args.pos], giterr_last()->message);
+	}


I'd use our usual error handling style instead.

if (err < 0) { printf("failed..."); goto cleanup; } err = perform_checkout_ref(repo, checkout_target, &opts);

pks-t · 2018-06-29T13:16:14Z

+
+	neg_opt = malloc(strlen(opt) + 3);
+	strcpy(neg_opt, "--no-");
+	strcat(neg_opt, opt + 2);


This seems a bit heavy-handed ;)

if (!strncmp(found, "--no-", strlen("--no-")) && !strcmp(found + strlen("--no-"), opt + 2)) { *out = 0; res = 1; }

This is untested, but something like that would work.

Nice, that's soo much better !

pks-t · 2018-06-29T13:19:37Z

+
+#ifdef _MSC_VER
+#define snprintf sprintf_s
+#endif


This is unused

tiennou · 2018-06-30T13:09:58Z

I've fixed/clarified most of the review comments. Clarifications because sometime™ we might want to demonstrate path-based checkouts, so the code in main was convoluted because of that.

The code is also commented now.

pks-t · 2018-07-06T08:14:36Z

+		res = 1;
+	}
+
+	return res;


You could avoid the res variable by just returning 1 in the previous branch and 0 at the end of this function. That would make the asymmetry between the first and second conditional go away. Not urgent though, you should only address this if you're rerolling anyway

pks-t · 2018-07-06T08:15:28Z

+ * Check current `args` entry against a "bool" `opt` (ie. --[no-]progress).
+ * If `opt` matches positively, out will be set to 1, or if `opt` matches
+ * negatively, out will be set to 0, and 1 will be returned.
+ * If neither the positive or the negative form of opt matched, out will be -1,


The documentation is wrong. You either set out to 0 or 1, but never -1.

pks-t · 2018-07-06T08:17:31Z

+		const char *curr = args->argv[args->pos];
+		int bool_arg;
+
+		if (strcmp(curr, "--") == 0) {


You should probably use !strcmp, for consistency with the next conditional. Might confuse readers otherwise

pks-t · 2018-07-06T08:31:26Z

+	if (git_annotated_commit_ref(target)) {
+		err = git_repository_set_head(repo, git_annotated_commit_ref(target));
+	} else {
+		err = git_repository_set_head_detached(repo, git_annotated_commit_id(target));


There's git_repository_set_head_detached_from_annotated

pks-t · 2018-07-06T08:32:49Z

+		print_usage();
+
+	/* Default values */
+	opts->progress = 1;


You should memset(opts, 0, sizeof(opts)), as you never initialize the struct to all-zeroes

pks-t · 2018-07-06T08:35:57Z

+	}
+
+	if (args.pos >= args.argc) {
+		fprintf(stderr, "unhandled\n");


Shouldn't this check be part of parse_options, together with usage instructions? I'd expect that function to only ever return where the options are correct

pks-t · 2018-07-06T08:36:39Z

+
+		fprintf(stderr, "unhandled path-based checkout\n");
+		err = 1;
+		goto cleanup;


I'd also just remove this and error out in parse_options in case where paths are given. It makes the remaining logic a bit easier to read, I guess

pks-t · 2018-07-06T08:38:17Z

+		/**
+		 * Try to resolve a "refish" argument to a target libgit2 can use
+		 */
+		err = resolve_refish(&checkout_target, repo, args.argv[args.pos]);


Resolving the ref here makes sense, but I'd parse the reference itself into the options structure in parse_options

As git_annotated_commit seems to behave like cgit's refish, it's quite helpful to abstract away "targets" via git_annotated_commit_from_id/from_ref. As the former is accessible via git_annotated_commit_id, make the latter also available to users.

tiennou · 2018-07-07T13:03:28Z

I've fixed some of the comments.

It seems we have a slight difference in how we expect option parsing to happen though, so here's my "view" : I can't access libgit2 while parsing options, because there might be a --git-dir option after the current argument (option which I'm using to test), so I can't resolve refishs, or paths, because the "current working directory" might be updated later. Hence, I really much prefer option parsing to be kept dumb, and I think it actually makes more sense as example code (if you want to perform a checkout, you can basically look at what main() is doing and ignore the option parsing).

Also, I've attempted to handle path-based checkouts, but just ended up craving for libgit2's already written support for those (it only took one "any directory relative stat call" to throw my hands up at the incoming strcat mess 😉).

pks-t

It seems we have a slight difference in how we expect option parsing to happen though, so here's my "view" : I can't access libgit2 while parsing options, because there might be a --git-dir option after the current argument (option which I'm using to test), so I can't resolve refishs, or paths, because the "current working directory" might be updated later. Hence, I really much prefer option parsing to be kept dumb, and I think it actually makes more sense as example code (if you want to perform a checkout, you can basically look at what main() is doing and ignore the option parsing).

Fair enough, so be it.

I'm fine with this PR then, except for one instance of undefined behaviour. Ready to merge as soon as that's fixed.

pks-t · 2018-07-13T07:44:52Z

+
+/**
+ * This function is called to report progression, ie. it's called once with
+ * a NULL path and the number of total steps, then for each subsequent path,


If this function is indeed called with a NULL path, then the printf call is undefined behaviour as "%s" expects a valid pointer

tiennou · 2018-07-17T19:44:47Z

Fixed the UB. As always, thanks for the review @pks-t !

pks-t · 2018-07-20T11:07:09Z

And again, thanks @tiennou! :)

pks-t requested changes Jun 29, 2018

View reviewed changes

tiennou force-pushed the examples/checkout branch 2 times, most recently from b97c7ba to ffc3918 Compare June 30, 2018 13:05

tiennou mentioned this pull request Jun 30, 2018

add.c example doesn't display #4711

Open

pks-t requested changes Jul 6, 2018

View reviewed changes

tiennou added 4 commits July 7, 2018 13:10

examples: move refish resolution function in common

8a629af

examples: make the refish resolution work with short OIDs

8e063eb

examples: add a helper for boolean-style options

5b7ba78

tiennou force-pushed the examples/checkout branch from ffc3918 to 4570fd5 Compare July 7, 2018 12:52

pks-t requested changes Jul 13, 2018

View reviewed changes

examples: add checkout

b24202e

tiennou force-pushed the examples/checkout branch from 4570fd5 to b24202e Compare July 17, 2018 19:43

pks-t approved these changes Jul 19, 2018

View reviewed changes

pks-t merged commit ea9e2c1 into libgit2:master Jul 20, 2018

tiennou deleted the examples/checkout branch August 26, 2018 20:01

tiennou mentioned this pull request May 27, 2019

add example "do_checkout_ref" #2824

Closed

snyk-bot mentioned this pull request Feb 23, 2020

[Snyk] Upgrade nodegit from 0.4.1 to 0.26.4 saurabharch/Breezeblocks#1

Open

snyk-bot mentioned this pull request Apr 22, 2020

[Snyk] Upgrade nodegit from 0.24.3 to 0.26.5 aminatakonate000/Graviton-App#4

Open

snyk-bot mentioned this pull request May 5, 2020

[Snyk] Upgrade nodegit from 0.24.3 to 0.26.5 Barnstorm-Online/ngp-openapi-generator#1

Open

Conversation

tiennou commented Jun 23, 2018

Uh oh!

tiennou commented Jun 23, 2018

Uh oh!

pks-t left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tiennou commented Jun 30, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tiennou commented Jul 7, 2018

Uh oh!

pks-t left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tiennou commented Jul 17, 2018

Uh oh!

pks-t commented Jul 20, 2018

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants