Re: [PATCH 0/7] teach `worktree list` verbose mode and prunable annotations
flat view
From: Eric Sunshine <hidden>
Date: 2021-01-06 05:37:40
On Mon, Jan 4, 2021 at 11:22 AM Rafael Silva [off-list ref] wrote:
In c57b3367be (worktree: teach `list` to annotate locked worktree, 2020-10-11) we taught `git worktree list` to annotate working tree that is locked by appending "locked" text in order to signalize to the user that a working tree is locked. During the review, there was some discussion about additional annotations and information that `list` command could provide to the user that has long been envisioned and mentioned in [2], [3] and [4]. This patch series address some of these changes by teaching `worktree list` to show "prunable" annotation, adding verbose mode and extending the --porcelain format with prunable and locked annotation as follow up from [1]. Additionally, it address one shortcoming for porcelain format to escape any newline characters (LF and CRLF) for the lock reason to prevent breaking format mentioned in [4] and [1] during the review cycle.
Thank you for working on this. I'm happy to see these long-envisioned enhancements finally taking shape. Before even reviewing the patches, I decided to apply them and play with the new features, and I'm very pleased to see that they behave exactly as I had envisioned all those years ago. Very nicely done. I'll review the patches when I finish responding to this cover letter.
The first moves the should_prune_worktree() machinery to the top-level worktree.c exposing the function as general API, that will be reference by should_prune_worktree() wrapper implemented on the second patch. The original idea was to not only move should_prune_worktree() but also refactor to accept "struct worktree" and load the information directly, which can simplify the `prune` command by reusing get_worktrees(). However this seems to also require refactoring get_worktrees() itself to return "non-valid" working trees that can/should be pruned. This is also mentioned in [5]. Having the wrapper function makes it easier to add the prunable annotation without touching the get_worktrees() and the other worktree sub commands. The refactoring can be addressed in a future patch, if this turns out to be good idea. One possible approach is to teach get_worktrees() to take additional flags that will tell whether to return only valid or all worktrees in GIT_DIR/worktrees/ directory and address its own possible shortcoming, if any.
I haven't looked at the patches yet, so I can't respond to this right now.
The third patch changes worktree_lock_reason() to be more gentle for the main working tree to simply returning NULL instead of aborting the program via assert() macro. This allow us to simplify the code that checks if the working tree is locked for default and porcelain format. This changes is also mentioned in [6].
Sounds good.
The forth patch is the one that teaches `list` command to show prunable annotation, for both default and porcelain format, and adds the verbose option. These changes are also done for the "locked" annotation that was not done on in [1]. Additionally, `list` learns to fail when both --verbose and --porcelain format as used together.
My knee-jerk response to disallowing --verbose and --porcelain together was that it seemed unnecessarily harsh, but upon reflection, I think it's the correct thing to do. After all, porcelain output, even though extensible and flexible, should be predictable, so it doesn't make sense for options such as --verbose to affect it.
The fifth patch adds worktree_escape_reason() that accepts a (char *) text and returned the text with any LF or CRLF escaped. The caller is responsible to freeing the escaped text. This is used by the locked annotation in porcelain format. Currently, this is defined within builtin/worktree.c as I was not sure whether libfying the function as part of this series is a good idea. At this time it seems more sensible to leave the code internally and libfying later once we are confident about the implementation and whether it can be used in other part of the code base but I'm open for suggestion.
Perhaps I misunderstand, but I had envisioned employing one of the codebase's existing quoting/escaping functions rather than crafting a new one from scratch. However, I'll reserve judgment until I actually read the patch.