git/trailer.h, branch v2.45.2

trailer: finish formatting unification

2024-03-15T17:10:25Z

Rename format_trailer_info() to format_trailers(). Finally, both interpret-trailers and format_trailers_from_commit() can call "format_trailers()"! Update the comment in to remove the (now obsolete) caveats about format_trailers_from_commit(). Those caveats come from a388b10fc1 (pretty: move trailer formatting to trailer.c, 2017-08-15) where it says: pretty: move trailer formatting to trailer.c The next commit will add many features to the %(trailer) placeholder in pretty.c. We'll need to access some internal functions of trailer.c for that, so our options are either: 1. expose those functions publicly or 2. make an entry point into trailer.c to do the formatting Doing (2) ends up exposing less surface area, though do note that caveats in the docstring of the new function. which suggests format_trailers_from_commit() started out from pretty.c and did not have access to all of the trailer implementation internals, and was never intended to replace (unify) the formatting machinery in trailer.c. The refactors leading up to this commit (as well as additional refactors that will follow) expose additional functions publicly, and is therefore choosing option (1) as described in a388b10fc1. Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

trailer: begin formatting unification

2024-03-15T17:10:25Z

Now that the preparatory refactors are over, we can replace the call to format_trailers() in interpret-trailers with format_trailer_info(). This unifies the trailer formatting machinery In order to avoid breakages in t7502 and t7513, we have to steal the features present in format_trailers(). Namely, we have to teach format_trailer_info() as follows: (1) make it aware of opts->trim_empty, and (2) make it avoid hardcoding ": " as the separator and space (which can result in double-printing these characters). For (2), make it only print the separator and space if we cannot find any recognized separator somewhere in the key (yes, keys may have a trailing separator in it --- we will eventually fix this design but not now). Do so by copying the code out of print_tok_val(), and deleting the same function. Helped-by: Junio C Hamano Helped-by: Christian Couder Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

format_trailers(): use strbuf instead of FILE

2024-03-01T18:35:42Z

This is another preparatory refactor to unify the trailer formatters. Make format_trailers() also write to a strbuf, to align with format_trailers_from_commit() which also does the same. Doing this makes format_trailers() behave similar to format_trailer_info() (which will soon help us replace one with the other). Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

trailer_info_get(): reorder parameters

2024-03-01T18:35:42Z

This is another preparatory refactor to unify the trailer formatters. Take const struct process_trailer_options *opts as the first parameter, because these options are required for parsing trailers (e.g., whether to treat "---" as the end of the log message). And take struct trailer_info *info last, because it's an "out parameter" (something that the caller wants to use as the output of this function). Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

trailer: move interpret_trailers() to interpret-trailers.c

2024-03-01T18:35:42Z

The interpret-trailers.c builtin is the only place we need to call interpret_trailers(), so move its definition there (together with a few helper functions called only by it) and remove its external declaration from . Several helper functions that are called by interpret_trailers() remain in trailer.c because other callers in the same file still call them. Declare them in so that interpret_trailers() (now in builtin/interpret-trailers.c) can continue calling them as a trailer API user. This enriches with a more granular API, which can then be unit-tested in the future (because interpret_trailers() by itself does too many things to be able to be easily unit-tested). Take this opportunity to demote some file-handling functions out of the trailer API implementation, as these have nothing to do with trailers. Helped-by: Junio C Hamano Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

trailer: reorder format_trailers_from_commit() parameters

2024-03-01T18:35:42Z

Currently there are two functions for formatting trailers in : void format_trailers(const struct process_trailer_options *, struct list_head *trailers, FILE *outfile); void format_trailers_from_commit(struct strbuf *out, const char *msg, const struct process_trailer_options *opts); and although they are similar enough (even taking the same process_trailer_options struct pointer) they are used quite differently. One might intuitively think that format_trailers_from_commit() builds on top of format_trailers(), but this is not the case. Instead format_trailers_from_commit() calls format_trailer_info() and format_trailers() is never called in that codepath. This is a preparatory refactor to help us deprecate format_trailers() in favor of format_trailer_info() (at which point we can rename the latter to the former). When the deprecation is complete, both format_trailers_from_commit(), and the interpret-trailers builtin will be able to call into the same helper function (instead of format_trailers() and format_trailer_info(), respectively). Unifying the formatters is desirable because it simplifies the API. Reorder parameters for format_trailers_from_commit() to prefer const struct process_trailer_options *opts as the first parameter, because these options are intimately tied to formatting trailers. And take struct strbuf *out last, because it's an "out parameter" (something that the caller wants to use as the output of this function). Similarly, reorder parameters for format_trailer_info(), because later on we will unify the two together. Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

trailer: rename functions to use 'trailer'

2024-03-01T18:35:42Z

Rename process_trailers() to interpret_trailers(), because it matches the name for the builtin command of the same name (git-interpret-trailers), which is the sole user of process_trailers(). In a following commit, we will move "interpret_trailers" from trailer.c to builtin/interpret-trailers.c. That move will necessitate the growth of the trailer.h API, forcing us to expose some additional functions in trailer.h. Rename relevant functions so that they include the term "trailer" in their name, so that clients of the API will be able to easily identify them by their "trailer" moniker, just like all the other functions already exposed by trailer.h. Rename `struct list_head *head` to `struct list_head *trailers` because "head" conveys no additional information beyond the "list_head" type. Reorder parameters for format_trailers_from_commit() to prefer const struct process_trailer_options *opts as the first parameter, because these options are intimately tied to formatting trailers. Parameters like `FILE *outfile` should be last because they are a kind of 'out' parameter, so put such parameters at the end. This will be the pattern going forward in this series. Helped-by: Junio C Hamano Helped-by: Christian Couder Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

trailer: use offsets for trailer_start/trailer_end

2023-12-20T19:55:04Z

Previously these fields in the trailer_info struct were of type "const char *" and pointed to positions in the input string directly (to the start and end positions of the trailer block). Use offsets to make the intended usage less ambiguous. We only need to reference the input string in format_trailer_info(), so update that function to take a pointer to the input. While we're at it, rename trailer_start to trailer_block_start to be more explicit about these offsets (that they are for the entire trailer block including other trailers). Ditto for trailer_end. Reported-by: Glen Choo Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

trailer: separate public from internal portion of trailer_iterator

2023-09-11T17:01:18Z

The fields here are not meant to be used by downstream callers, so put them behind an anonymous struct named as "internal" to warn against their use. This follows the pattern in 576de3d956 (unpack_trees: start splitting internal fields from public API, 2023-02-27). Signed-off-by: Linus Arver Signed-off-by: Junio C Hamano

pretty format %(trailers): add a "key_value_separator"

2020-12-09T22:16:42Z

Add a "key_value_separator" option to the "%(trailers)" pretty format, to go along with the existing "separator" argument. In combination these two options make it trivial to produce machine-readable (e.g. \0 and \0\0-delimited) format output. As elaborated on in a previous commit which added "keyonly" it was needlessly tedious to extract structured data from "%(trailers)" before the addition of this "key_value_separator" option. As seen by the test being added here extracting this data now becomes trivial. Signed-off-by: Ævar Arnfjörð Bjarmason Signed-off-by: Junio C Hamano