threads / patch / 53354

patch, 5 partsshallow: extract a header file

Subject: [PATCH 0/5] shallow: extract a header file

## tl;dr

22 messages between Apr 29, 2020 and Apr 30, 2020. Diffs are folded; open one to read it.

replies: 21people: 4as markdown or json

Taylor Blau· Apr 29, 2020, 22:39 UTC · lore
Hi,

These few patches are based on a suggestion in [1] from Jonathan Nieder and in [2] Junio. The gist of this series is to do the following three things:

  1. Extract a new 'shallow.h' header to collect all of the functions
     that are related to shallow-ness, but defined in 'commit.h'.
  2. Add some documentation from the previous series where it could have
     benefited from it.
  3. Finally, introduce a thin wrapper type 'struct shallow_lock' which
     makes it a type-level error to unlock a non-shallow lock with
     '{commit,rollback}_shallow_file'.

The remainder of suggestions in [1] about the structure of t5537 I decided to not address in this series, since I anticipate there is more work there than I want to take on in this series alone.

Thanks in advance for your review!

[1]: https://lore.kernel.org/git/20200423011444.GG140314@google.com/ [2]: https://lore.kernel.org/git/xmqqy2qnidyy.fsf@gitster.c.googlers.com/

Taylor Blau (5):
  commit: make 'commit_graft_pos' non-static
  shallow: extract a header file for shallow-related functions
  commit: move 'unregister_shallow' to 'shallow.h'
  shallow.h: document '{commit,rollback}_shallow_file'
  shallow: use struct 'shallow_lock' for additional safety
 builtin.h              |  1 +
 builtin/receive-pack.c |  2 +-
 commit.c               | 16 ++-------
 commit.h               | 49 +-------------------------
 fetch-pack.c           |  3 +-
 send-pack.c            |  1 +
 shallow.c              | 36 +++++++++++++------
 shallow.h              | 78 ++++++++++++++++++++++++++++++++++++++++++
 upload-pack.c          |  1 +
 9 files changed, 112 insertions(+), 75 deletions(-)
 create mode 100644 shallow.h

-- 2.26.0.113.ge9739cdccc

Taylor Blau· Apr 29, 2020, 22:39 UTC · re: Taylor Blau · lore

[PATCH 1/5] commit: make 'commit_graft_pos' non-static

In the next patch, some functions will be moved from 'commit.c' to have prototypes in a new 'shallow.h' and their implementations in 'shallow.c'.

Three functions in 'commit.c' use 'commit_graft_pos()' (they are 'register_commit_graft()', 'lookup_commit_graft()', and 'unregister_shallow()'). The first two of these will stay in 'commit.c', but the latter will move to 'shallow.c', and thus needs 'commit_graft_pos' to be non-static.

Prepare for that by making 'commit_graft_pos' non-static so that it can be called from both 'commit.c' and 'shallow.c'.

Signed-off-by: Taylor Blau <me@ttaylorr.com>
---
 commit.c | 2 +-
 commit.h | 1 +
 2 files changed, 2 insertions(+), 1 deletion(-)
Show changes to 2 files +2 −1

commit.c, commit.h

diff --git a/commit.c b/commit.c
index c7099daeac..b76f7d72be 100644
--- a/commit.c
+++ b/commit.c
@@ -110,7 +110,7 @@ static const unsigned char *commit_graft_sha1_access(size_t index, void *table)
 	return commit_graft_table[index]->oid.hash;
 }
 
-static int commit_graft_pos(struct repository *r, const unsigned char *sha1)
+int commit_graft_pos(struct repository *r, const unsigned char *sha1)
 {
 	return sha1_pos(sha1, r->parsed_objects->grafts,
 			r->parsed_objects->grafts_nr,
diff --git a/commit.h b/commit.h
index ab91d21131..eb42e8b6d2 100644
--- a/commit.h
+++ b/commit.h
@@ -236,6 +236,7 @@ struct commit_graft {
 typedef int (*each_commit_graft_fn)(const struct commit_graft *, void *);
 
 struct commit_graft *read_graft_line(struct strbuf *line);
+int commit_graft_pos(struct repository *r, const unsigned char *sha1);
 int register_commit_graft(struct repository *r, struct commit_graft *, int);
 void prepare_commit_graft(struct repository *r);
 struct commit_graft *lookup_commit_graft(struct repository *r, const struct object_id *oid);
-- 
2.26.0.113.ge9739cdccc
Jonathan Nieder· Apr 30, 2020, 03:26 UTC · re: Taylor Blau · lore

Re: [PATCH 1/5] commit: make 'commit_graft_pos' non-static

Hi,
Taylor Blau wrote:
Show 18 quoted lines
>            [...] by making 'commit_graft_pos' non-static so that it can
> be called from both 'commit.c' and 'shallow.c'.
>
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
> ---
>  commit.c | 2 +-
>  commit.h | 1 +
>  2 files changed, 2 insertions(+), 1 deletion(-)
> 
> diff --git a/commit.h b/commit.h
> index ab91d21131..eb42e8b6d2 100644
> --- a/commit.h
> +++ b/commit.h
> @@ -236,6 +236,7 @@ struct commit_graft {
>  typedef int (*each_commit_graft_fn)(const struct commit_graft *, void *);
>  
>  struct commit_graft *read_graft_line(struct strbuf *line);
> +int commit_graft_pos(struct repository *r, const unsigned char *sha1);

Now that this function isn't file-local, its name becomes more significant. What array does this represent a position in? What does it return if the graft isn't found? From a call site it's not necessarily obvious.

Ideas:
- could include a comment saying that it's an index into
  r->parsed_objects->grafts
- I'm usually loathe to suggest unnecessary duplication of code, but
  it might make sense to duplicate the function into shallow.c.  Or
  even to inline it there (in the single call site, that ends up
  being pretty readable).
Thoughts?

Thanks, Jonathan

Taylor Blau· Apr 30, 2020, 19:22 UTC · re: Jonathan Nieder · lore

Re: [PATCH 1/5] commit: make 'commit_graft_pos' non-static

On Wed, Apr 29, 2020 at 08:26:11PM -0700, Jonathan Nieder wrote:
Show 33 quoted lines
> Hi,
>
> Taylor Blau wrote:
>
>
> >            [...] by making 'commit_graft_pos' non-static so that it can
> > be called from both 'commit.c' and 'shallow.c'.
> >
> > Signed-off-by: Taylor Blau <me@ttaylorr.com>
> > ---
> >  commit.c | 2 +-
> >  commit.h | 1 +
> >  2 files changed, 2 insertions(+), 1 deletion(-)
> >
> > diff --git a/commit.h b/commit.h
> > index ab91d21131..eb42e8b6d2 100644
> > --- a/commit.h
> > +++ b/commit.h
> > @@ -236,6 +236,7 @@ struct commit_graft {
> >  typedef int (*each_commit_graft_fn)(const struct commit_graft *, void *);
> >
> >  struct commit_graft *read_graft_line(struct strbuf *line);
> > +int commit_graft_pos(struct repository *r, const unsigned char *sha1);
>
> Now that this function isn't file-local, its name becomes more
> significant.  What array does this represent a position in?  What does
> it return if the graft isn't found?  From a call site it's not
> necessarily obvious.
>
> Ideas:
>
> - could include a comment saying that it's an index into
>   r->parsed_objects->grafts

This and the below are both good ideas to me. I prefer this one, since we'd have to duplicate yet another static function ('commit_graft_sha1_access()' directly above) that is called by this one.

> - I'm usually loathe to suggest unnecessary duplication of code, but
>   it might make sense to duplicate the function into shallow.c.  Or
>   even to inline it there (in the single call site, that ends up
>   being pretty readable).

I am not at all offended by duplication of code where it makes sense to do so, but having to duplicate two functions seems like we'd be better off simply documenting the function in commit.h.

> Thoughts?
>
> Thanks,
> Jonathan

Thanks, Taylor

Taylor Blau· Apr 29, 2020, 22:39 UTC · re: Taylor Blau · lore

[PATCH 2/5] shallow: extract a header file for shallow-related functions

There are many functions in commit.h that are more related to shallow repositories than they are to any sort of generic commit machinery. Likely this began when there were only a few shallow-related functions, and commit.h seemed a reasonable enough place to put them.

But, now there are a good number of shallow-related functions, and placing them all in 'commit.h' doesn't make sense.

This patch extracts a 'shallow.h', which takes all of the headers from 'commit.h' for functions which already exist in 'shallow.c'. We will bring the remaining shallow-related functions defined in 'commit.c' in a subsequent patch.

For now, move only the ones that already are implemented in 'shallow.c', and update the necessary includes.

Signed-off-by: Taylor Blau <me@ttaylorr.com>
---
 builtin.h     |  1 +
 commit.c      |  1 +
 commit.h      | 48 ---------------------------------------
 fetch-pack.c  |  1 +
 send-pack.c   |  1 +
 shallow.c     |  1 +
 shallow.h     | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++
 upload-pack.c |  1 +
 8 files changed, 69 insertions(+), 48 deletions(-)
 create mode 100644 shallow.h
Show changes to 8 files +69 −48

builtin.h, commit.c, commit.h, fetch-pack.c, send-pack.c, shallow.c, shallow.h, upload-pack.c

diff --git a/builtin.h b/builtin.h
index 2b25a80cde..2e701a023c 100644
--- a/builtin.h
+++ b/builtin.h
@@ -5,6 +5,7 @@
 #include "strbuf.h"
 #include "cache.h"
 #include "commit.h"
+#include "shallow.h"
 
 /*
  * builtin API
diff --git a/commit.c b/commit.c
index b76f7d72be..eebfbeb45d 100644
--- a/commit.c
+++ b/commit.c
@@ -20,6 +20,7 @@
 #include "refs.h"
 #include "commit-reach.h"
 #include "run-command.h"
+#include "shallow.h"
 
 static struct commit_extra_header *read_commit_extra_header_lines(const char *buf, size_t len, const char **);
 
diff --git a/commit.h b/commit.h
index eb42e8b6d2..5cd984939b 100644
--- a/commit.h
+++ b/commit.h
@@ -248,55 +248,7 @@ struct commit *get_fork_point(const char *refname, struct commit *commit);
 
 struct oid_array;
 struct ref;
-int register_shallow(struct repository *r, const struct object_id *oid);
-int unregister_shallow(const struct object_id *oid);
-int commit_shallow_file(struct repository *r, struct lock_file *lk);
-void rollback_shallow_file(struct repository *r, struct lock_file *lk);
 int for_each_commit_graft(each_commit_graft_fn, void *);
-int is_repository_shallow(struct repository *r);
-struct commit_list *get_shallow_commits(struct object_array *heads,
-					int depth, int shallow_flag, int not_shallow_flag);
-struct commit_list *get_shallow_commits_by_rev_list(
-		int ac, const char **av, int shallow_flag, int not_shallow_flag);
-void set_alternate_shallow_file(struct repository *r, const char *path, int override);
-int write_shallow_commits(struct strbuf *out, int use_pack_protocol,
-			  const struct oid_array *extra);
-void setup_alternate_shallow(struct lock_file *shallow_lock,
-			     const char **alternate_shallow_file,
-			     const struct oid_array *extra);
-const char *setup_temporary_shallow(const struct oid_array *extra);
-void advertise_shallow_grafts(int);
-
-/*
- * Initialize with prepare_shallow_info() or zero-initialize (equivalent to
- * prepare_shallow_info with a NULL oid_array).
- */
-struct shallow_info {
-	struct oid_array *shallow;
-	int *ours, nr_ours;
-	int *theirs, nr_theirs;
-	struct oid_array *ref;
-
-	/* for receive-pack */
-	uint32_t **used_shallow;
-	int *need_reachability_test;
-	int *reachable;
-	int *shallow_ref;
-	struct commit **commits;
-	int nr_commits;
-};
-
-void prepare_shallow_info(struct shallow_info *, struct oid_array *);
-void clear_shallow_info(struct shallow_info *);
-void remove_nonexistent_theirs_shallow(struct shallow_info *);
-void assign_shallow_commits_to_refs(struct shallow_info *info,
-				    uint32_t **used,
-				    int *ref_status);
-int delayed_reachability_test(struct shallow_info *si, int c);
-#define PRUNE_SHOW_ONLY 1
-#define PRUNE_QUICK 2
-void prune_shallow(unsigned options);
-extern struct trace_key trace_shallow;
 
 int interactive_add(int argc, const char **argv, const char *prefix, int patch);
 int run_add_interactive(const char *revision, const char *patch_mode,
diff --git a/fetch-pack.c b/fetch-pack.c
index a618f3b029..401d028e41 100644
--- a/fetch-pack.c
+++ b/fetch-pack.c
@@ -22,6 +22,7 @@
 #include "connected.h"
 #include "fetch-negotiator.h"
 #include "fsck.h"
+#include "shallow.h"
 
 static int transfer_unpack_limit = -1;
 static int fetch_unpack_limit = -1;
diff --git a/send-pack.c b/send-pack.c
index 0407841ae8..e0ccfef75a 100644
--- a/send-pack.c
+++ b/send-pack.c
@@ -15,6 +15,7 @@
 #include "sha1-array.h"
 #include "gpg-interface.h"
 #include "cache.h"
+#include "shallow.h"
 
 int option_parse_push_signed(const struct option *opt,
 			     const char *arg, int unset)
diff --git a/shallow.c b/shallow.c
index 5010a6c732..d0191c7609 100644
--- a/shallow.c
+++ b/shallow.c
@@ -14,6 +14,7 @@
 #include "commit-slab.h"
 #include "list-objects.h"
 #include "commit-reach.h"
+#include "shallow.h"
 
 void set_alternate_shallow_file(struct repository *r, const char *path, int override)
 {
diff --git a/shallow.h b/shallow.h
new file mode 100644
index 0000000000..14dd748625
--- /dev/null
+++ b/shallow.h
@@ -0,0 +1,63 @@
+#ifndef SHALLOW_H
+#define SHALLOW_H
+
+#include "lockfile.h"
+#include "object.h"
+#include "repository.h"
+#include "strbuf.h"
+
+void set_alternate_shallow_file(struct repository *r, const char *path, int override);
+int register_shallow(struct repository *r, const struct object_id *oid);
+int is_repository_shallow(struct repository *r);
+int commit_shallow_file(struct repository *r, struct lock_file *lk);
+void rollback_shallow_file(struct repository *r, struct lock_file *lk);
+
+struct commit_list *get_shallow_commits(struct object_array *heads,
+					int depth, int shallow_flag, int not_shallow_flag);
+struct commit_list *get_shallow_commits_by_rev_list(
+		int ac, const char **av, int shallow_flag, int not_shallow_flag);
+int write_shallow_commits(struct strbuf *out, int use_pack_protocol,
+			  const struct oid_array *extra);
+
+void setup_alternate_shallow(struct lock_file *shallow_lock,
+			     const char **alternate_shallow_file,
+			     const struct oid_array *extra);
+
+const char *setup_temporary_shallow(const struct oid_array *extra);
+
+void advertise_shallow_grafts(int);
+
+#define PRUNE_SHOW_ONLY 1
+#define PRUNE_QUICK 2
+void prune_shallow(unsigned options);
+
+/*
+ * Initialize with prepare_shallow_info() or zero-initialize (equivalent to
+ * prepare_shallow_info with a NULL oid_array).
+ */
+struct shallow_info {
+	struct oid_array *shallow;
+	int *ours, nr_ours;
+	int *theirs, nr_theirs;
+	struct oid_array *ref;
+
+	/* for receive-pack */
+	uint32_t **used_shallow;
+	int *need_reachability_test;
+	int *reachable;
+	int *shallow_ref;
+	struct commit **commits;
+	int nr_commits;
+};
+
+void prepare_shallow_info(struct shallow_info *, struct oid_array *);
+void clear_shallow_info(struct shallow_info *);
+void remove_nonexistent_theirs_shallow(struct shallow_info *);
+void assign_shallow_commits_to_refs(struct shallow_info *info,
+				    uint32_t **used,
+				    int *ref_status);
+int delayed_reachability_test(struct shallow_info *si, int c);
+
+extern struct trace_key trace_shallow;
+
+#endif /* SHALLOW_H */
diff --git a/upload-pack.c b/upload-pack.c
index c53249cac1..e71b068291 100644
--- a/upload-pack.c
+++ b/upload-pack.c
@@ -26,6 +26,7 @@
 #include "serve.h"
 #include "commit-graph.h"
 #include "commit-reach.h"
+#include "shallow.h"
 
 /* Remember to update object flag allocation in object.h */
 #define THEY_HAVE	(1u << 11)
-- 
2.26.0.113.ge9739cdccc
Eric Sunshine· Apr 29, 2020, 22:48 UTC · re: Taylor Blau · lore

Re: [PATCH 2/5] shallow: extract a header file for shallow-related functions

On Wed, Apr 29, 2020 at 6:39 PM Taylor Blau <me@ttaylorr.com> wrote:
Show 9 quoted lines
> There are many functions in commit.h that are more related to shallow
> repositories than they are to any sort of generic commit machinery.
> Likely this began when there were only a few shallow-related functions,
> and commit.h seemed a reasonable enough place to put them.
>
> But, now there are a good number of shallow-related functions, and
> placing them all in 'commit.h' doesn't make sense.
>
> This patch extracts a 'shallow.h', which takes all of the headers from
Did you mean s/headers/declarations/ ?
Show 8 quoted lines
> 'commit.h' for functions which already exist in 'shallow.c'. We will
> bring the remaining shallow-related functions defined in 'commit.c' in a
> subsequent patch.
>
> For now, move only the ones that already are implemented in 'shallow.c',
> and update the necessary includes.
>
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
Jonathan Tan· Apr 30, 2020, 00:21 UTC · re: Taylor Blau · lore

Re: [PATCH 2/5] shallow: extract a header file for shallow-related functions

First of all, I couldn't apply these patches neither on latest master (86ab15cb15 ("The fourth batch", 2020-04-28)) nor on its 2 immediate ancestors - what is the base of these patches? (Or is there something wrong with my workflow?)

I'll review based on the patches themselves, but what I've seen looks good so far.

Show 9 quoted lines
> diff --git a/builtin.h b/builtin.h
> index 2b25a80cde..2e701a023c 100644
> --- a/builtin.h
> +++ b/builtin.h
> @@ -5,6 +5,7 @@
>  #include "strbuf.h"
>  #include "cache.h"
>  #include "commit.h"
> +#include "shallow.h"

It's a pity that builtin.h has to be modified in this way, but I see that it's necessary - a few files that include builtin.h (at least git.c and builtin/bisect--helper.c) assume that they have shallow function access through this header.

Once I manage to apply these patches myself, I'll verify with --color-moved that the lines moved as I expect, but otherwise patch 1 and 2 look good.

Taylor Blau· Apr 30, 2020, 00:59 UTC · re: Jonathan Tan · lore

Re: [PATCH 2/5] shallow: extract a header file for shallow-related functions

Hi Jonathan,
On Wed, Apr 29, 2020 at 05:21:54PM -0700, Jonathan Tan wrote:
> First of all, I couldn't apply these patches neither on latest master
> (86ab15cb15 ("The fourth batch", 2020-04-28)) nor on its 2 immediate
> ancestors - what is the base of these patches? (Or is there something
> wrong with my workflow?)

Yes, I should have mentioned in the cover letter that this is based on 'tb/reset-shallow' which is should be part of Junio's next push to master. I didn't mention it because I figured that it would be on master by the time anyone wanted to look at these patches ;).

Anyhow, apologies. It should apply cleanly on any branch that has 'tb/reset-shallow' already.

Show 17 quoted lines
> I'll review based on the patches themselves, but what I've seen looks
> good so far.
>
> > diff --git a/builtin.h b/builtin.h
> > index 2b25a80cde..2e701a023c 100644
> > --- a/builtin.h
> > +++ b/builtin.h
> > @@ -5,6 +5,7 @@
> >  #include "strbuf.h"
> >  #include "cache.h"
> >  #include "commit.h"
> > +#include "shallow.h"
>
> It's a pity that builtin.h has to be modified in this way, but I see
> that it's necessary - a few files that include builtin.h (at least git.c
> and builtin/bisect--helper.c) assume that they have shallow function
> access through this header.
Yeah :/.
> Once I manage to apply these patches myself, I'll verify with
> --color-moved that the lines moved as I expect, but otherwise patch 1
> and 2 look good.
Thanks.

Thanks, Taylor

Jonathan Tan· Apr 30, 2020, 18:23 UTC · re: Taylor Blau · lore

Re: [PATCH 2/5] shallow: extract a header file for shallow-related functions

Show 7 quoted lines
> Yes, I should have mentioned in the cover letter that this is based on
> 'tb/reset-shallow' which is should be part of Junio's next push to
> master. I didn't mention it because I figured that it would be on master
> by the time anyone wanted to look at these patches ;).
> 
> Anyhow, apologies. It should apply cleanly on any branch that has
> 'tb/reset-shallow' already.

Thanks. Now that I'm able to apply the patches, I see that the prototype for unregister_shallow() was removed with no corresponding addition. This causes a compile error when running "make" with DEVELOPER=1. Other than that, things look fine.

Jonathan Nieder· Apr 30, 2020, 03:19 UTC · re: Taylor Blau · lore

Re: [PATCH 2/5] shallow: extract a header file for shallow-related functions

Taylor Blau wrote:
Show 7 quoted lines
> There are many functions in commit.h that are more related to shallow
> repositories than they are to any sort of generic commit machinery.
> Likely this began when there were only a few shallow-related functions,
> and commit.h seemed a reasonable enough place to put them.
>
> But, now there are a good number of shallow-related functions, and
> placing them all in 'commit.h' doesn't make sense.
Sure.  For me, there are a few additional sources of motivation:
- shallow clone is a bit of a thorny feature, so I like having the
  indication of which source files are interacting with it
- this will give us a good place to put any overview documentation on
  the shallow API
Show 7 quoted lines
> This patch extracts a 'shallow.h', which takes all of the headers from
> 'commit.h' for functions which already exist in 'shallow.c'. We will
> bring the remaining shallow-related functions defined in 'commit.c' in a
> subsequent patch.
>
> For now, move only the ones that already are implemented in 'shallow.c',
> and update the necessary includes.
It's probably worth a mention of the builtin.h part here.

(By the way, I wouldn't be against propagating that to the callers, to better match what https://include-what-you-use.org/ would enforce.)

Thanks, Jonathan

Taylor Blau· Apr 29, 2020, 22:39 UTC · re: Taylor Blau · lore

[PATCH 3/5] commit: move 'unregister_shallow' to 'shallow.h'

In the last commit, we introduced a header for the functions defined in 'shallow.c'. There is one remaining shallow-related function in commit.c which should be moved, too. This patch moves that function.

Signed-off-by: Taylor Blau <me@ttaylorr.com>
---
 commit.c  | 13 -------------
 shallow.c | 13 +++++++++++++
 shallow.h |  1 +
 3 files changed, 14 insertions(+), 13 deletions(-)
Show changes to 3 files +14 −13

commit.c, shallow.c, shallow.h

diff --git a/commit.c b/commit.c
index eebfbeb45d..87686a7055 100644
--- a/commit.c
+++ b/commit.c
@@ -246,19 +246,6 @@ int for_each_commit_graft(each_commit_graft_fn fn, void *cb_data)
 	return ret;
 }
 
-int unregister_shallow(const struct object_id *oid)
-{
-	int pos = commit_graft_pos(the_repository, oid->hash);
-	if (pos < 0)
-		return -1;
-	if (pos + 1 < the_repository->parsed_objects->grafts_nr)
-		MOVE_ARRAY(the_repository->parsed_objects->grafts + pos,
-			   the_repository->parsed_objects->grafts + pos + 1,
-			   the_repository->parsed_objects->grafts_nr - pos - 1);
-	the_repository->parsed_objects->grafts_nr--;
-	return 0;
-}
-
 struct commit_buffer {
 	void *buffer;
 	unsigned long size;
diff --git a/shallow.c b/shallow.c
index d0191c7609..76e00893fe 100644
--- a/shallow.c
+++ b/shallow.c
@@ -39,6 +39,19 @@ int register_shallow(struct repository *r, const struct object_id *oid)
 	return register_commit_graft(r, graft, 0);
 }
 
+int unregister_shallow(const struct object_id *oid)
+{
+	int pos = commit_graft_pos(the_repository, oid->hash);
+	if (pos < 0)
+		return -1;
+	if (pos + 1 < the_repository->parsed_objects->grafts_nr)
+		MOVE_ARRAY(the_repository->parsed_objects->grafts + pos,
+			   the_repository->parsed_objects->grafts + pos + 1,
+			   the_repository->parsed_objects->grafts_nr - pos - 1);
+	the_repository->parsed_objects->grafts_nr--;
+	return 0;
+}
+
 int is_repository_shallow(struct repository *r)
 {
 	FILE *fp;
diff --git a/shallow.h b/shallow.h
index 14dd748625..b50a85ed7e 100644
--- a/shallow.h
+++ b/shallow.h
@@ -8,6 +8,7 @@
 
 void set_alternate_shallow_file(struct repository *r, const char *path, int override);
 int register_shallow(struct repository *r, const struct object_id *oid);
+int unregister_shallow(const struct object_id *oid);
 int is_repository_shallow(struct repository *r);
 int commit_shallow_file(struct repository *r, struct lock_file *lk);
 void rollback_shallow_file(struct repository *r, struct lock_file *lk);
-- 
2.26.0.113.ge9739cdccc
Jonathan Nieder· Apr 30, 2020, 03:13 UTC · re: Taylor Blau · lore

Re: [PATCH 3/5] commit: move 'unregister_shallow' to 'shallow.h'

Taylor Blau wrote:
Show 10 quoted lines
> In the last commit, we introduced a header for the functions defined in
> 'shallow.c'. There is one remaining shallow-related function in
> commit.c which should be moved, too. This patch moves that function.
> 
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
> ---
>  commit.c  | 13 -------------
>  shallow.c | 13 +++++++++++++
>  shallow.h |  1 +
>  3 files changed, 14 insertions(+), 13 deletions(-)
Yes, an obviously good thing to do.

Perhaps could be squashed with patch 1 (but also see my review of that one).

Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Should this take a "struct repository" parameter?
Taylor Blau· Apr 30, 2020, 19:29 UTC · re: Jonathan Nieder · lore

Re: [PATCH 3/5] commit: move 'unregister_shallow' to 'shallow.h'

On Wed, Apr 29, 2020 at 08:13:50PM -0700, Jonathan Nieder wrote:
Show 17 quoted lines
> Taylor Blau wrote:
>
> > In the last commit, we introduced a header for the functions defined in
> > 'shallow.c'. There is one remaining shallow-related function in
> > commit.c which should be moved, too. This patch moves that function.
> >
> > Signed-off-by: Taylor Blau <me@ttaylorr.com>
> > ---
> >  commit.c  | 13 -------------
> >  shallow.c | 13 +++++++++++++
> >  shallow.h |  1 +
> >  3 files changed, 14 insertions(+), 13 deletions(-)
>
> Yes, an obviously good thing to do.
>
> Perhaps could be squashed with patch 1 (but also see my review of that
> one).

Do you mean patch 2/5? If so, I think that it probably makes more sense to go there than in the first patch.

(I originally thought that it would be useful for people reading the diff to have this change broken out into its own patch, but I think that it's more juggling to do in terms of figuring out which headers to include than is worth.)

> Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
>
> Should this take a "struct repository" parameter?

Probably, but I'd rather leave this series to be just focused on moving this code around while being minimally invasive.

Thanks, Taylor

Taylor Blau· Apr 29, 2020, 22:39 UTC · re: Taylor Blau · lore

[PATCH 4/5] shallow.h: document '{commit,rollback}_shallow_file'

When 'commit_shallow_file()' and 'rollback_shallow_file()' were introduced, they did not have an documenting comment, when they could have benefited from one.

Add a brief note about what these functions do, and make a special note that they reset stat-validity checks.

Signed-off-by: Taylor Blau <me@ttaylorr.com>
---
 shallow.h | 4 ++++
 1 file changed, 4 insertions(+)
Show changes to shallow.h +4 −0
diff --git a/shallow.h b/shallow.h
index b50a85ed7e..08e1bc4fd0 100644
--- a/shallow.h
+++ b/shallow.h
@@ -10,6 +10,10 @@ void set_alternate_shallow_file(struct repository *r, const char *path, int over
 int register_shallow(struct repository *r, const struct object_id *oid);
 int unregister_shallow(const struct object_id *oid);
 int is_repository_shallow(struct repository *r);
+/*
+ * {commit,rollback}_shallow_file commits or performs a rollback to the
+ * '.git/shallow' file, respectively, and resets stat-validity checks.
+ */
 int commit_shallow_file(struct repository *r, struct lock_file *lk);
 void rollback_shallow_file(struct repository *r, struct lock_file *lk);
 
-- 
2.26.0.113.ge9739cdccc
Eric Sunshine· Apr 29, 2020, 22:53 UTC · re: Taylor Blau · lore

Re: [PATCH 4/5] shallow.h: document '{commit,rollback}_shallow_file'

On Wed, Apr 29, 2020 at 6:39 PM Taylor Blau <me@ttaylorr.com> wrote:
> When 'commit_shallow_file()' and 'rollback_shallow_file()' were
> introduced, they did not have an documenting comment, when they could
> have benefited from one.

"an" seems wrong; did you mean "a" or "any"? Or, rewrite as: "...they were not documented...".

Show 16 quoted lines
> Add a brief note about what these functions do, and make a special note
> that they reset stat-validity checks.
>
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
> ---
> diff --git a/shallow.h b/shallow.h
> @@ -10,6 +10,10 @@ void set_alternate_shallow_file(struct repository *r, const char *path, int over
>  int register_shallow(struct repository *r, const struct object_id *oid);
>  int unregister_shallow(const struct object_id *oid);
>  int is_repository_shallow(struct repository *r);
> +/*
> + * {commit,rollback}_shallow_file commits or performs a rollback to the
> + * '.git/shallow' file, respectively, and resets stat-validity checks.
> + */
>  int commit_shallow_file(struct repository *r, struct lock_file *lk);
>  void rollback_shallow_file(struct repository *r, struct lock_file *lk);
Or, simpler:
    /* commit .git/shallow and reset stat-validity checks */
    int commit_shallow_file(...);
    /* rollback .git/shallow and reset stat-validity checks */
    void rollback_shallow_file(...);
Taylor Blau· Apr 29, 2020, 22:39 UTC · re: Taylor Blau · lore

[PATCH 5/5] shallow: use struct 'shallow_lock' for additional safety

In previous patches, the functions 'commit_shallow_file' and 'rollback_shallow_file' were introduced to reset the shallowness validity checks on a repository after potentially modifying '.git/shallow'.

These functions can be made safer by wrapping the 'struct lockfile *' in a new type, 'shallow_lock', so that they cannot be called with a raw lock (and potentially misused by other code that happens to possess a lockfile, but has nothing to do with shallowness).

This patch introduces that type as a thin wrapper around 'struct lockfile', and updates the two aforementioned functions and their callers to use it.

Suggested-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Taylor Blau <me@ttaylorr.com>
---
 builtin/receive-pack.c |  2 +-
 fetch-pack.c           |  2 +-
 shallow.c              | 22 +++++++++++-----------
 shallow.h              | 16 +++++++++++++---
 4 files changed, 26 insertions(+), 16 deletions(-)
Show changes to 4 files +26 −16

builtin/receive-pack.c, fetch-pack.c, shallow.c, shallow.h

diff --git a/builtin/receive-pack.c b/builtin/receive-pack.c
index 652661fa99..10fd2c52ec 100644
--- a/builtin/receive-pack.c
+++ b/builtin/receive-pack.c
@@ -855,7 +855,7 @@ static void refuse_unconfigured_deny_delete_current(void)
 static int command_singleton_iterator(void *cb_data, struct object_id *oid);
 static int update_shallow_ref(struct command *cmd, struct shallow_info *si)
 {
-	struct lock_file shallow_lock = LOCK_INIT;
+	struct shallow_lock shallow_lock = SHALLOW_LOCK_INIT;
 	struct oid_array extra = OID_ARRAY_INIT;
 	struct check_connected_options opt = CHECK_CONNECTED_INIT;
 	uint32_t mask = 1 << (cmd->index % 32);
diff --git a/fetch-pack.c b/fetch-pack.c
index 401d028e41..27d2d08cc0 100644
--- a/fetch-pack.c
+++ b/fetch-pack.c
@@ -35,7 +35,7 @@ static int fetch_fsck_objects = -1;
 static int transfer_fsck_objects = -1;
 static int agent_supported;
 static int server_supports_filtering;
-static struct lock_file shallow_lock;
+static struct shallow_lock shallow_lock;
 static const char *alternate_shallow_file;
 static struct strbuf fsck_msg_types = STRBUF_INIT;
 
diff --git a/shallow.c b/shallow.c
index 76e00893fe..1acf8ce95b 100644
--- a/shallow.c
+++ b/shallow.c
@@ -92,16 +92,16 @@ static void reset_repository_shallow(struct repository *r)
 	stat_validity_clear(r->parsed_objects->shallow_stat);
 }
 
-int commit_shallow_file(struct repository *r, struct lock_file *lk)
+int commit_shallow_file(struct repository *r, struct shallow_lock *lk)
 {
-	int res = commit_lock_file(lk);
+	int res = commit_lock_file(&lk->lk);
 	reset_repository_shallow(r);
 	return res;
 }
 
-void rollback_shallow_file(struct repository *r, struct lock_file *lk)
+void rollback_shallow_file(struct repository *r, struct shallow_lock *lk)
 {
-	rollback_lock_file(lk);
+	rollback_lock_file(&lk->lk);
 	reset_repository_shallow(r);
 }
 
@@ -366,22 +366,22 @@ const char *setup_temporary_shallow(const struct oid_array *extra)
 	return "";
 }
 
-void setup_alternate_shallow(struct lock_file *shallow_lock,
+void setup_alternate_shallow(struct shallow_lock *shallow_lock,
 			     const char **alternate_shallow_file,
 			     const struct oid_array *extra)
 {
 	struct strbuf sb = STRBUF_INIT;
 	int fd;
 
-	fd = hold_lock_file_for_update(shallow_lock,
+	fd = hold_lock_file_for_update(&shallow_lock->lk,
 				       git_path_shallow(the_repository),
 				       LOCK_DIE_ON_ERROR);
 	check_shallow_file_for_update(the_repository);
 	if (write_shallow_commits(&sb, 0, extra)) {
 		if (write_in_full(fd, sb.buf, sb.len) < 0)
 			die_errno("failed to write to %s",
-				  get_lock_file_path(shallow_lock));
-		*alternate_shallow_file = get_lock_file_path(shallow_lock);
+				  get_lock_file_path(&shallow_lock->lk));
+		*alternate_shallow_file = get_lock_file_path(&shallow_lock->lk);
 	} else
 		/*
 		 * is_repository_shallow() sees empty string as "no
@@ -414,7 +414,7 @@ void advertise_shallow_grafts(int fd)
  */
 void prune_shallow(unsigned options)
 {
-	struct lock_file shallow_lock = LOCK_INIT;
+	struct shallow_lock shallow_lock = SHALLOW_LOCK_INIT;
 	struct strbuf sb = STRBUF_INIT;
 	unsigned flags = SEEN_ONLY;
 	int fd;
@@ -428,14 +428,14 @@ void prune_shallow(unsigned options)
 		strbuf_release(&sb);
 		return;
 	}
-	fd = hold_lock_file_for_update(&shallow_lock,
+	fd = hold_lock_file_for_update(&shallow_lock.lk,
 				       git_path_shallow(the_repository),
 				       LOCK_DIE_ON_ERROR);
 	check_shallow_file_for_update(the_repository);
 	if (write_shallow_commits_1(&sb, 0, NULL, flags)) {
 		if (write_in_full(fd, sb.buf, sb.len) < 0)
 			die_errno("failed to write to %s",
-				  get_lock_file_path(&shallow_lock));
+				  get_lock_file_path(&shallow_lock.lk));
 		commit_shallow_file(the_repository, &shallow_lock);
 	} else {
 		unlink(git_path_shallow(the_repository));
diff --git a/shallow.h b/shallow.h
index 08e1bc4fd0..d12096fbc4 100644
--- a/shallow.h
+++ b/shallow.h
@@ -10,12 +10,22 @@ void set_alternate_shallow_file(struct repository *r, const char *path, int over
 int register_shallow(struct repository *r, const struct object_id *oid);
 int unregister_shallow(const struct object_id *oid);
 int is_repository_shallow(struct repository *r);
+
+/*
+ * shallow_lock is a thin wrapper around 'struct lock_file' in order to restrict
+ * which locks can be used with '{commit,rollback}_shallow_file()'.
+ */
+struct shallow_lock {
+	struct lock_file lk;
+};
+#define SHALLOW_LOCK_INIT { LOCK_INIT }
+
 /*
  * {commit,rollback}_shallow_file commits or performs a rollback to the
  * '.git/shallow' file, respectively, and resets stat-validity checks.
  */
-int commit_shallow_file(struct repository *r, struct lock_file *lk);
-void rollback_shallow_file(struct repository *r, struct lock_file *lk);
+int commit_shallow_file(struct repository *r, struct shallow_lock *lk);
+void rollback_shallow_file(struct repository *r, struct shallow_lock *lk);
 
 struct commit_list *get_shallow_commits(struct object_array *heads,
 					int depth, int shallow_flag, int not_shallow_flag);
@@ -24,7 +34,7 @@ struct commit_list *get_shallow_commits_by_rev_list(
 int write_shallow_commits(struct strbuf *out, int use_pack_protocol,
 			  const struct oid_array *extra);
 
-void setup_alternate_shallow(struct lock_file *shallow_lock,
+void setup_alternate_shallow(struct shallow_lock *shallow_lock,
 			     const char **alternate_shallow_file,
 			     const struct oid_array *extra);
 
-- 
2.26.0.113.ge9739cdccc
Eric Sunshine· Apr 29, 2020, 23:03 UTC · re: Taylor Blau · lore

Re: [PATCH 5/5] shallow: use struct 'shallow_lock' for additional safety

On Wed, Apr 29, 2020 at 6:39 PM Taylor Blau <me@ttaylorr.com> wrote:
Show 16 quoted lines
> [...]
> This patch introduces that type as a thin wrapper around 'struct
> lockfile', and updates the two aforementioned functions and their
> callers to use it.
>
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
> ---
> diff --git a/shallow.h b/shallow.h
> @@ -10,12 +10,22 @@ void set_alternate_shallow_file(struct repository *r, const char *path, int over
> +/*
> + * shallow_lock is a thin wrapper around 'struct lock_file' in order to restrict
> + * which locks can be used with '{commit,rollback}_shallow_file()'.
> + */
> +struct shallow_lock {
> +       struct lock_file lk;
> +};

The documentation comment for 'shallow_lock' may help newcomers to C but probably doesn't add much value for seasoned programmers. If this is the sort of idiom we want to introduce (or exists already in this codebase) -- declaring a specific C type to avoid accidental use of an unrelated lock -- then it's probably better documented in CodingGuidelines rather than repeating it at each point in the code which employs the idiom.

Taylor Blau· Apr 29, 2020, 23:51 UTC · re: Eric Sunshine · lore

Re: [PATCH 5/5] shallow: use struct 'shallow_lock' for additional safety

On Wed, Apr 29, 2020 at 07:03:48PM -0400, Eric Sunshine wrote:
Show 25 quoted lines
> On Wed, Apr 29, 2020 at 6:39 PM Taylor Blau <me@ttaylorr.com> wrote:
> > [...]
> > This patch introduces that type as a thin wrapper around 'struct
> > lockfile', and updates the two aforementioned functions and their
> > callers to use it.
> >
> > Signed-off-by: Taylor Blau <me@ttaylorr.com>
> > ---
> > diff --git a/shallow.h b/shallow.h
> > @@ -10,12 +10,22 @@ void set_alternate_shallow_file(struct repository *r, const char *path, int over
> > +/*
> > + * shallow_lock is a thin wrapper around 'struct lock_file' in order to restrict
> > + * which locks can be used with '{commit,rollback}_shallow_file()'.
> > + */
> > +struct shallow_lock {
> > +       struct lock_file lk;
> > +};
>
> The documentation comment for 'shallow_lock' may help newcomers to C
> but probably doesn't add much value for seasoned programmers. If this
> is the sort of idiom we want to introduce (or exists already in this
> codebase) -- declaring a specific C type to avoid accidental use of an
> unrelated lock -- then it's probably better documented in
> CodingGuidelines rather than repeating it at each point in the code
> which employs the idiom.

Fair enough; I definitely weighed the usefulness of this comment a little bit when I was writing it. I figured that I didn't want to commit to updating CodingGuidelines in this series, but that I didn't want to leave the explanation only in the commit message.

I figure that it's probably fine to document it in the commit message, and leave it at that for now.

Thanks for this suggestion (and the earlier ones, too). I have applied them locally, and I'll sit on them for a day or two before sending out v2. Thanks again.

Thanks, Taylor

Jonathan Tan· Apr 30, 2020, 00:30 UTC · re: Taylor Blau · lore

Re: [PATCH 5/5] shallow: use struct 'shallow_lock' for additional safety

Show 17 quoted lines
> @@ -428,14 +428,14 @@ void prune_shallow(unsigned options)
>  		strbuf_release(&sb);
>  		return;
>  	}
> -	fd = hold_lock_file_for_update(&shallow_lock,
> +	fd = hold_lock_file_for_update(&shallow_lock.lk,
>  				       git_path_shallow(the_repository),
>  				       LOCK_DIE_ON_ERROR);
>  	check_shallow_file_for_update(the_repository);
>  	if (write_shallow_commits_1(&sb, 0, NULL, flags)) {
>  		if (write_in_full(fd, sb.buf, sb.len) < 0)
>  			die_errno("failed to write to %s",
> -				  get_lock_file_path(&shallow_lock));
> +				  get_lock_file_path(&shallow_lock.lk));
>  		commit_shallow_file(the_repository, &shallow_lock);
>  	} else {
>  		unlink(git_path_shallow(the_repository));

I was hoping that the inner lock ("lk") wouldn't need to be exposed, so that it wouldn't be possible to inadvertently commit the lock without going through commit_shallow_file(), but this patch is still a step towards that.

Show 16 quoted lines
> diff --git a/shallow.h b/shallow.h
> index 08e1bc4fd0..d12096fbc4 100644
> --- a/shallow.h
> +++ b/shallow.h
> @@ -10,12 +10,22 @@ void set_alternate_shallow_file(struct repository *r, const char *path, int over
>  int register_shallow(struct repository *r, const struct object_id *oid);
>  int unregister_shallow(const struct object_id *oid);
>  int is_repository_shallow(struct repository *r);
> +
> +/*
> + * shallow_lock is a thin wrapper around 'struct lock_file' in order to restrict
> + * which locks can be used with '{commit,rollback}_shallow_file()'.
> + */
> +struct shallow_lock {
> +	struct lock_file lk;
> +};

As far as I know, we don't use many abbreviations in struct members - maybe s/lk/lock/.

I couldn't find any other issues with all 5 patches in this patch series, but I would like to be able to apply the patches to be sure.

Jonathan Nieder· Apr 30, 2020, 03:11 UTC · re: Taylor Blau · lore

Re: [PATCH 5/5] shallow: use struct 'shallow_lock' for additional safety

Hi,
Taylor Blau wrote:
Show 22 quoted lines
> In previous patches, the functions 'commit_shallow_file' and
> 'rollback_shallow_file' were introduced to reset the shallowness
> validity checks on a repository after potentially modifying
> '.git/shallow'.
>
> These functions can be made safer by wrapping the 'struct lockfile *' in
> a new type, 'shallow_lock', so that they cannot be called with a raw
> lock (and potentially misused by other code that happens to possess a
> lockfile, but has nothing to do with shallowness).
>
> This patch introduces that type as a thin wrapper around 'struct
> lockfile', and updates the two aforementioned functions and their
> callers to use it.
>
> Suggested-by: Junio C Hamano <gitster@pobox.com>
> Signed-off-by: Taylor Blau <me@ttaylorr.com>
> ---
>  builtin/receive-pack.c |  2 +-
>  fetch-pack.c           |  2 +-
>  shallow.c              | 22 +++++++++++-----------
>  shallow.h              | 16 +++++++++++++---
>  4 files changed, 26 insertions(+), 16 deletions(-)
Yay!  Thanks for indulging the suggestion.
[...]
Show 15 quoted lines
> --- a/shallow.h
> +++ b/shallow.h
> @@ -10,12 +10,22 @@ void set_alternate_shallow_file(struct repository *r, const char *path, int over
>  int register_shallow(struct repository *r, const struct object_id *oid);
>  int unregister_shallow(const struct object_id *oid);
>  int is_repository_shallow(struct repository *r);
> +
> +/*
> + * shallow_lock is a thin wrapper around 'struct lock_file' in order to restrict
> + * which locks can be used with '{commit,rollback}_shallow_file()'.
> + */
> +struct shallow_lock {
> +	struct lock_file lk;
> +};
> +#define SHALLOW_LOCK_INIT { LOCK_INIT }

I think I disagree with Eric here: it's useful to have a comment here to describe the purpose of the struct (i.e., the "why" as opposed to the "what").

I wonder if we can go further, though --- when using a shallow_lock, how should I think of it as a caller? In some sense, the use of 'struct lock_file' is an implementation detail, so we could say:

	/*
	 * Lock for updating the $GIT_DIR/shallow file.
	 *
	 * Use `commit_shallow_file()` to commit an update, or
	 * `rollback_shallow_file()` to roll it back.  In either case,
	 * any in-memory cached information about which commits are
	 * shallow will be appropriately invalidated so that future
	 * operations reflect the new state.
	 */
What do you think?
[...]
> --- a/shallow.c
> +++ b/shallow.c
[...]
Show 16 quoted lines
> @@ -366,22 +366,22 @@ const char *setup_temporary_shallow(const struct oid_array *extra)
>  	return "";
>  }
>  
> -void setup_alternate_shallow(struct lock_file *shallow_lock,
> +void setup_alternate_shallow(struct shallow_lock *shallow_lock,
>  			     const char **alternate_shallow_file,
>  			     const struct oid_array *extra)
>  {
>  	struct strbuf sb = STRBUF_INIT;
>  	int fd;
>  
> -	fd = hold_lock_file_for_update(shallow_lock,
> +	fd = hold_lock_file_for_update(&shallow_lock->lk,
>  				       git_path_shallow(the_repository),
>  				       LOCK_DIE_ON_ERROR);

This is peeking into the underlying lock_file, so I should ask myself whether it's hinting at some missing function in the shallow_lock API. My feeling is "no": setup_alternate_shallow is itself that function. :)

[...]
Show 24 quoted lines
> @@ -414,7 +414,7 @@ void advertise_shallow_grafts(int fd)
>   */
>  void prune_shallow(unsigned options)
>  {
> -	struct lock_file shallow_lock = LOCK_INIT;
> +	struct shallow_lock shallow_lock = SHALLOW_LOCK_INIT;
>  	struct strbuf sb = STRBUF_INIT;
>  	unsigned flags = SEEN_ONLY;
>  	int fd;
> @@ -428,14 +428,14 @@ void prune_shallow(unsigned options)
>  		strbuf_release(&sb);
>  		return;
>  	}
> -	fd = hold_lock_file_for_update(&shallow_lock,
> +	fd = hold_lock_file_for_update(&shallow_lock.lk,
>  				       git_path_shallow(the_repository),
>  				       LOCK_DIE_ON_ERROR);
>  	check_shallow_file_for_update(the_repository);
>  	if (write_shallow_commits_1(&sb, 0, NULL, flags)) {
>  		if (write_in_full(fd, sb.buf, sb.len) < 0)
>  			die_errno("failed to write to %s",
> -				  get_lock_file_path(&shallow_lock));
> +				  get_lock_file_path(&shallow_lock.lk));
>  		commit_shallow_file(the_repository, &shallow_lock);

There's no obvious helper to extract here either, so this looks good to me.

With whatever tweaks based on Eric's and Jonathan's reviews seem appropriate,

Reviewed-by: Jonathan Nieder <jrnieder@gmail.com>
Thanks.
Eric Sunshine· Apr 30, 2020, 05:32 UTC · re: Jonathan Nieder · lore

Re: [PATCH 5/5] shallow: use struct 'shallow_lock' for additional safety

On Wed, Apr 29, 2020 at 11:11 PM Jonathan Nieder <jrnieder@gmail.com> wrote:
Show 9 quoted lines
> Taylor Blau wrote:
> > +/*
> > + * shallow_lock is a thin wrapper around 'struct lock_file' in order to restrict
> > + * which locks can be used with '{commit,rollback}_shallow_file()'.
> > + */
>
> I think I disagree with Eric here: it's useful to have a comment here
> to describe the purpose of the struct (i.e., the "why" as opposed to
> the "what").

I'm not, in general, opposed to the structure being documented; it's just that the comment, as presented, doesn't seem to add value.

Show 15 quoted lines
> I wonder if we can go further, though --- when using a shallow_lock,
> how should I think of it as a caller? In some sense, the use of
> 'struct lock_file' is an implementation detail, so we could say:
>
>     /*
>     * Lock for updating the $GIT_DIR/shallow file.
>     *
>     * Use `commit_shallow_file()` to commit an update, or
>     * `rollback_shallow_file()` to roll it back. In either case,
>     * any in-memory cached information about which commits are
>     * shallow will be appropriately invalidated so that future
>     * operations reflect the new state.
>     */
>
> What do you think?

This comment makes more sense and wouldn't have led to me questioning its usefulness. Thanks.

Taylor Blau· Apr 30, 2020, 19:32 UTC · re: Eric Sunshine · lore

Re: [PATCH 5/5] shallow: use struct 'shallow_lock' for additional safety

On Thu, Apr 30, 2020 at 01:32:34AM -0400, Eric Sunshine wrote:
Show 32 quoted lines
> On Wed, Apr 29, 2020 at 11:11 PM Jonathan Nieder <jrnieder@gmail.com> wrote:
> > Taylor Blau wrote:
> > > +/*
> > > + * shallow_lock is a thin wrapper around 'struct lock_file' in order to restrict
> > > + * which locks can be used with '{commit,rollback}_shallow_file()'.
> > > + */
> >
> > I think I disagree with Eric here: it's useful to have a comment here
> > to describe the purpose of the struct (i.e., the "why" as opposed to
> > the "what").
>
> I'm not, in general, opposed to the structure being documented; it's
> just that the comment, as presented, doesn't seem to add value.
>
> > I wonder if we can go further, though --- when using a shallow_lock,
> > how should I think of it as a caller? In some sense, the use of
> > 'struct lock_file' is an implementation detail, so we could say:
> >
> >     /*
> >     * Lock for updating the $GIT_DIR/shallow file.
> >     *
> >     * Use `commit_shallow_file()` to commit an update, or
> >     * `rollback_shallow_file()` to roll it back. In either case,
> >     * any in-memory cached information about which commits are
> >     * shallow will be appropriately invalidated so that future
> >     * operations reflect the new state.
> >     */
> >
> > What do you think?
>
> This comment makes more sense and wouldn't have led to me questioning
> its usefulness. Thanks.
Me either, thanks for the suggestion.

Thanks, Taylor

← back to recent threads