@matheusbsbs / matheus-bagliano / commits / a80c4c2214
Fork 0

worktree: improve find_worktree() documentation

Do a better job of explaining that find_worktree()'s main purpose is to locate a worktree based upon input from a user which may be some sort of shorthand for identifying a worktree rather than an actual path. For instance, one shorthand a user can use to identify a worktree is by unique path suffix (i.e. given worktrees at paths "foo/bar" and "foo/baz", the latter can be identified simply as "baz"). The actual heuristics find_worktree() uses to select a worktree may be expanded in the future (for instance, one day it may allow worktree selection by <id> of the .git/worktrees/<id>/ administrative directory), thus the documentation does not provide a precise description of how matching is performed, instead leaving it open-ended to allow for future enhancement. While at it, drop mention of the non-NULL requirement of `prefix` since NULL has long been allowed. For instance, prefix_filename() has explicitly allowed NULL since 116fb64e43 (prefix_filename: drop length parameter, 2017-03-20), and find_worktree() itself since e4da43b1f0 (prefix_filename: return newly allocated string, 2017-03-20). Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Eric Sunshine committed Feb 24, 2020 at 04:08 UTC a80c4c22147bae6d9f9b907b81ab3f4d129ab690
1 file changed +12 -2
worktree.h
+12 -2
@@ -44,8 +44,18 @@ int submodule_uses_worktrees(const char *path);
44 const char *get_worktree_git_dir(const struct worktree *wt);
45
46 /*
47 - * Search a worktree that can be unambiguously identified by
48 - * "arg". "prefix" must not be NULL.
47 + * Search for the worktree identified unambiguously by `arg` -- typically
48 + * supplied by the user via the command-line -- which may be a pathname or some
49 + * shorthand uniquely identifying a worktree, thus making it convenient for the
50 + * user to specify a worktree with minimal typing. For instance, if the last
51 + * component (say, "foo") of a worktree's pathname is unique among worktrees
52 + * (say, "work/foo" and "work/bar"), it can be used to identify the worktree
53 + * unambiguously.
54 + *
55 + * `prefix` should be the `prefix` handed to top-level Git commands along with
56 + * `argc` and `argv`.
57 + *
58 + * Return the worktree identified by `arg`, or NULL if not found.
59 */
60 struct worktree *find_worktree(struct worktree **list,
61 const char *prefix,