Skip to contentSkip to conversation

trailer: spread usage of "trailer_block" language

PATCH In review Linus Arver via GitGitGadget 5 participants 7 messages Oct 13, 2024 – Nov 12, 2024

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 trailer: spread usage of "trailer_block" language

From: Linus Arver <[email protected]>

Deprecate the "trailer_info" struct name and replace it with "trailer_block". This is more readable, for two reasons:

1. "trailer_info" on the surface sounds like it's about a single trailer when in reality it is a collection of one or more trailers, and

2. the "*_block" suffix is more informative than "*_info", because it describes a block (or region) of contiguous text which has trailers in it, which has been parsed into the trailer_block structure.

Rename the

    size_t trailer_block_start, trailer_block_end;

members of trailer_info to just "start" and "end". Rename the "info" pointer to "trailer_block" because it is more descriptive. Update comments accordingly.

---
trailer: spread usage of "trailer_block" language

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-1811%2Flistx%2Ftrailer-cleanup-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-1811/listx/trailer-cleanup-v1
Pull-Request: https://github.com/git/git/pull/1811

 builtin/interpret-trailers.c | 25 +++++-----
 trailer.c                    | 95 ++++++++++++++++++------------------
 trailer.h                    | 30 ++++++------
 3 files changed, 76 insertions(+), 74 deletions(-)
builtin/interpret-trailers.c +13 -12
index c5e56e2cd3d..44d8ccddc9d 100644
@@ -141,8 +141,8 @@ static void interpret_trailers(const struct process_trailer_options *opts,
 {
 	LIST_HEAD(head);
 	struct strbuf sb = STRBUF_INIT;
-	struct strbuf trailer_block = STRBUF_INIT;
-	struct trailer_info *info;
+	struct strbuf trailer_block_sb = STRBUF_INIT;
+	struct trailer_block *trailer_block;
 	FILE *outfile = stdout;
 
 	trailer_config_init();
@@ -152,13 +152,13 @@ static void interpret_trailers(const struct process_trailer_options *opts,
 	if (opts->in_place)
 		outfile = create_in_place_tempfile(file);
 
-	info = parse_trailers(opts, sb.buf, &head);
+	trailer_block = parse_trailers(opts, sb.buf, &head);
 
-	/* Print the lines before the trailers */
+	/* Print the lines before the trailer block */
 	if (!opts->only_trailers)
-		fwrite(sb.buf, 1, trailer_block_start(info), outfile);
+		fwrite(sb.buf, 1, trailer_block_start(trailer_block), outfile);
 
-	if (!opts->only_trailers && !blank_line_before_trailer_block(info))
+	if (!opts->only_trailers && !blank_line_before_trailer_block(trailer_block))
 		fprintf(outfile, "\n");
 
 
@@ -172,15 +172,16 @@ static void interpret_trailers(const struct process_trailer_options *opts,
 	}
 
 	/* Print trailer block. */
-	format_trailers(opts, &head, &trailer_block);
+	format_trailers(opts, &head, &trailer_block_sb);
 	free_trailers(&head);
-	fwrite(trailer_block.buf, 1, trailer_block.len, outfile);
-	strbuf_release(&trailer_block);
+	fwrite(trailer_block_sb.buf, 1, trailer_block_sb.len, outfile);
+	strbuf_release(&trailer_block_sb);
 
-	/* Print the lines after the trailers as is */
+	/* Print the lines after the trailer block as is. */
 	if (!opts->only_trailers)
-		fwrite(sb.buf + trailer_block_end(info), 1, sb.len - trailer_block_end(info), outfile);
-	trailer_info_release(info);
+		fwrite(sb.buf + trailer_block_end(trailer_block), 1,
+		       sb.len - trailer_block_end(trailer_block), outfile);
+	trailer_block_release(trailer_block);
 
 	if (opts->in_place)
 		if (rename_tempfile(&trailers_tempfile, file))
trailer.c +48 -47

192 lines not on this page · raw message

trailer.h +15 -15
index 6eb53df155e..4740549586a 100644
@@ -4,7 +4,7 @@
 #include "list.h"
 #include "strbuf.h"
 
-struct trailer_info;
+struct trailer_block;
 struct strvec;
 
 enum trailer_where {
@@ -72,12 +72,12 @@ void process_trailers_lists(struct list_head *head,
 			    struct list_head *arg_head);
 
 /*
- * Given some input string "str", return a pointer to an opaque trailer_info
+ * Given some input string "str", return a pointer to an opaque trailer_block
  * structure. Also populate the trailer_objects list with parsed trailer
  * objects. Internally this calls trailer_info_get() to get the opaque pointer,
  * but does some extra work to populate the trailer_objects linked list.
  *
- * The opaque trailer_info pointer can be used to check the position of the
+ * The opaque trailer_block pointer can be used to check the position of the
  * trailer block as offsets relative to the beginning of "str" in
  * trailer_block_start() and trailer_block_end().
  * blank_line_before_trailer_block() returns 1 if there is a blank line just
@@ -89,21 +89,21 @@ void process_trailers_lists(struct list_head *head,
  * For iterating through the parsed trailer block (if you don't care about the
  * position of the trailer block itself in the context of the larger string text
  * from which it was parsed), please see trailer_iterator_init() which uses the
- * trailer_info struct internally.
+ * trailer_block struct internally.
  *
  * Lastly, callers should call trailer_info_release() when they are done using
  * the opaque pointer.
  *
- * NOTE: Callers should treat both trailer_info and trailer_objects as
- * read-only items, because there is some overlap between the two (trailer_info
+ * NOTE: Callers should treat both trailer_block and trailer_objects as
+ * read-only items, because there is some overlap between the two (trailer_block
  * has "char **trailers" string array, and trailer_objects will have the same
  * data but as a linked list of trailer_item objects). This API does not perform
  * any synchronization between the two. In the future we should be able to
  * reduce the duplication and use just the linked list.
  */
-struct trailer_info *parse_trailers(const struct process_trailer_options *,
-				    const char *str,
-				    struct list_head *trailer_objects);
+struct trailer_block *parse_trailers(const struct process_trailer_options *,
+				     const char *str,
+				     struct list_head *trailer_objects);
 
 /*
  * Return the offset of the start of the trailer block. That is, 0 is the start
@@ -111,24 +111,24 @@ struct trailer_info *parse_trailers(const struct process_trailer_options *,
  * indicates how many bytes we have to skip over before we get to the beginning
  * of the trailer block.
  */
-size_t trailer_block_start(struct trailer_info *);
+size_t trailer_block_start(struct trailer_block *);
 
 /*
  * Return the end of the trailer block, again relative to the start of the
  * input.
  */
-size_t trailer_block_end(struct trailer_info *);
+size_t trailer_block_end(struct trailer_block *);
 
 /*
  * Return 1 if the trailer block had an extra newline (blank line) just before
  * it.
  */
-int blank_line_before_trailer_block(struct trailer_info *);
+int blank_line_before_trailer_block(struct trailer_block *);
 
 /*
- * Free trailer_info struct.
+ * Free trailer_block struct.
  */
-void trailer_info_release(struct trailer_info *info);
+void trailer_block_release(struct trailer_block *);
 
 void trailer_config_init(void);
 void format_trailers(const struct process_trailer_options *,
@@ -167,7 +167,7 @@ struct trailer_iterator {
 
 	/* private */
 	struct {
-		struct trailer_info *info;
+		struct trailer_block *trailer_block;
 		size_t cur;
 	} internal;
 };

base-commit: ef8ce8f3d4344fd3af049c17eeba5cd20d98b69f

Signature · 1 line
gitgitgadget
#1 lore raw
Quoted 2 lines · Linus Arver via GitGitGadget

From: Linus Arver <[email protected]>

Hmm. I just noticed that GGG (?) is somehow inferring my defunct @google.com address. Not sure how to fix this... any tips?

#2 lore raw
Quoted 7 lines · Linus Arver
Quoted 2 lines · Linus Arver via GitGitGadget

From: Linus Arver <[email protected]>

Hmm. I just noticed that GGG (?) is somehow inferring my defunct @google.com address. Not sure how to fix this... any tips?

Perhaps Johannes (CC'd) would know?

Thanks,
Taylor

#3 lore raw
In reply to Linus Arver

Hi Linus,

Quoted 7 lines · Linus Arver
Quoted 2 lines · Linus Arver via GitGitGadget

From: Linus Arver <[email protected]>

Hmm. I just noticed that GGG (?) is somehow inferring my defunct @google.com address. Not sure how to fix this... any tips?

This email address is apparently part of the commit object, see
https://github.com/git/git/commit/a556a5c05c44e521b572d595d5d32cc4158612c0.patch

(you can also see it locally if you call git show --no-mailmap a556a5c05c44e521b572d595d5d32cc4158612c0, but not if you omit --no-mailmap)

Ciao,
Johannes

#5 lore raw
In reply to Linus Arver via GitGitGadget
Quoted 13 lines · Linus Arver via GitGitGadget

From: Linus Arver <[email protected]>

Deprecate the "trailer_info" struct name and replace it with "trailer_block". This is more readable, for two reasons:

1. "trailer_info" on the surface sounds like it's about a single trailer when in reality it is a collection of one or more trailers, and

2. the "*_block" suffix is more informative than "*_info", because it describes a block (or region) of contiguous text which has trailers in it, which has been parsed into the trailer_block structure.

Quoted 7 lines

Rename the

    size_t trailer_block_start, trailer_block_end;

members of trailer_info to just "start" and "end". Rename the "info" pointer to "trailer_block" because it is more descriptive. Update comments accordingly.

All makes sense. Often "_info" suffix has very low information density, as everything is "info" in a sense ;-)

This was a more-or-less mechanical and straight-forward renaming of a handful of variables and structure fields. It is a shame that nobody bothered to review these changes (or say "this does not make anything worse, but is it worth it?" to object to it, for that matter) for almost a month.

Will merge to 'next' (unless there is a belated "it may not break, but it is not a good idea because ...", that is).

Thanks.

#4 lore raw
In reply to Johannes Schindelin
Quoted 12 lines · Johannes Schindelin

Hi Linus,

Quoted 7 lines · Linus Arver
Quoted 2 lines · Linus Arver via GitGitGadget

From: Linus Arver <[email protected]>

Hmm. I just noticed that GGG (?) is somehow inferring my defunct @google.com address. Not sure how to fix this... any tips?

Quoted 6 lines

This email address is apparently part of the commit object, see
https://github.com/git/git/commit/a556a5c05c44e521b572d595d5d32cc4158612c0.patch

(you can also see it locally if you call git show --no-mailmap a556a5c05c44e521b572d595d5d32cc4158612c0, but not if you omit --no-mailmap)

Ah, thanks! So the commit's Author field is actually set to the google email, but tig and other Git subcommands were using the .mailmap file to replace it with the proper (ucla) one. I didn't realize this was happening, and didn't bother updating the commit itself to use the email.

#6 lore raw
In reply to Junio C Hamano
Quoted 17 lines · Junio C Hamano
Quoted 15 lines · Linus Arver via GitGitGadget

From: Linus Arver <[email protected]>

Deprecate the "trailer_info" struct name and replace it with "trailer_block". This is more readable, for two reasons:

1. "trailer_info" on the surface sounds like it's about a single trailer when in reality it is a collection of one or more trailers, and

2. the "*_block" suffix is more informative than "*_info", because it describes a block (or region) of contiguous text which has trailers in it, which has been parsed into the trailer_block structure.

Rename the

Quoted 8 lines
Quoted 5 lines
    size_t trailer_block_start, trailer_block_end;

members of trailer_info to just "start" and "end". Rename the "info" pointer to "trailer_block" because it is more descriptive. Update comments accordingly.

All makes sense. Often "_info" suffix has very low information density, as everything is "info" in a sense ;-)

Exactly.

Quoted 2 lines

Will merge to 'next' (unless there is a belated "it may not break, but it is not a good idea because ...", that is).

Yup, sounds good. Thanks!