* [PATCH] clone: support 'clone --shared' from a worktree @ 2017-12-11 23:16 Eric Sunshine 2017-12-12 0:01 ` Junio C Hamano 2017-12-12 0:18 ` Brandon Williams 0 siblings, 2 replies; 8+ messages in thread From: Eric Sunshine @ 2017-12-11 23:16 UTC (permalink / raw) To: git; +Cc: Marc-André Lureau, Eric Sunshine When worktree functionality was originally implemented, the possibility of 'clone --local' from within a worktree was overlooked, with the result that the location of the "objects" directory of the source repository was computed incorrectly, thus the objects could not be copied or hard-linked by the clone. This shortcoming was addressed by 744e469755 (clone: allow --local from a linked checkout, 2015-09-28). However, the related case of 'clone --shared' (despite being handled only a few lines away from the 'clone --local' case) was not fixed by 744e469755, with a similar result of the "objects" directory location being incorrectly computed for insertion into the 'alternates' file. Fix this. Reported-by: Marc-André Lureau <marcandre.lureau@gmail.com> Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> --- builtin/clone.c | 3 ++- t/t2025-worktree-add.sh | 6 ++++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/builtin/clone.c b/builtin/clone.c index b22845738a..6ad0ab3fa4 100644 --- a/builtin/clone.c +++ b/builtin/clone.c @@ -452,7 +452,8 @@ static void clone_local(const char *src_repo, const char *dest_repo) { if (option_shared) { struct strbuf alt = STRBUF_INIT; - strbuf_addf(&alt, "%s/objects", src_repo); + get_common_dir(&alt, src_repo); + strbuf_addstr(&alt, "/objects"); add_to_alternates_file(alt.buf); strbuf_release(&alt); } else { diff --git a/t/t2025-worktree-add.sh b/t/t2025-worktree-add.sh index b5c47ac602..7395973318 100755 --- a/t/t2025-worktree-add.sh +++ b/t/t2025-worktree-add.sh @@ -245,6 +245,12 @@ test_expect_success 'local clone from linked checkout' ' ( cd here-clone && git fsck ) ' +test_expect_success 'local clone --shared from linked checkout' ' + git -C bare worktree add --detach ../baretree && + git clone --local --shared baretree bare-clone && + grep /bare/ bare-clone/.git/objects/info/alternates +' + test_expect_success '"add" worktree with --no-checkout' ' git worktree add --no-checkout -b swamp swamp && ! test -e swamp/init.t && -- 2.15.1.502.gccaef8de57 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] clone: support 'clone --shared' from a worktree 2017-12-11 23:16 [PATCH] clone: support 'clone --shared' from a worktree Eric Sunshine @ 2017-12-12 0:01 ` Junio C Hamano 2017-12-12 0:18 ` Brandon Williams 1 sibling, 0 replies; 8+ messages in thread From: Junio C Hamano @ 2017-12-12 0:01 UTC (permalink / raw) To: Eric Sunshine; +Cc: git, Marc-André Lureau Eric Sunshine <sunshine@sunshineco.com> writes: > When worktree functionality was originally implemented, the possibility > of 'clone --local' from within a worktree was overlooked, with the > result that the location of the "objects" directory of the source > repository was computed incorrectly, thus the objects could not be > copied or hard-linked by the clone. This shortcoming was addressed by > 744e469755 (clone: allow --local from a linked checkout, 2015-09-28). > > However, the related case of 'clone --shared' (despite being handled > only a few lines away from the 'clone --local' case) was not fixed by > 744e469755, with a similar result of the "objects" directory location > being incorrectly computed for insertion into the 'alternates' file. > Fix this. > > Reported-by: Marc-André Lureau <marcandre.lureau@gmail.com> > Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> > --- > builtin/clone.c | 3 ++- > t/t2025-worktree-add.sh | 6 ++++++ > 2 files changed, 8 insertions(+), 1 deletion(-) > > diff --git a/builtin/clone.c b/builtin/clone.c > index b22845738a..6ad0ab3fa4 100644 > --- a/builtin/clone.c > +++ b/builtin/clone.c > @@ -452,7 +452,8 @@ static void clone_local(const char *src_repo, const char *dest_repo) > { > if (option_shared) { > struct strbuf alt = STRBUF_INIT; > - strbuf_addf(&alt, "%s/objects", src_repo); > + get_common_dir(&alt, src_repo); > + strbuf_addstr(&alt, "/objects"); > add_to_alternates_file(alt.buf); > strbuf_release(&alt); > } else { Makes sense. Will queue. Thanks. ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] clone: support 'clone --shared' from a worktree 2017-12-11 23:16 [PATCH] clone: support 'clone --shared' from a worktree Eric Sunshine 2017-12-12 0:01 ` Junio C Hamano @ 2017-12-12 0:18 ` Brandon Williams 2017-12-12 0:40 ` Eric Sunshine 1 sibling, 1 reply; 8+ messages in thread From: Brandon Williams @ 2017-12-12 0:18 UTC (permalink / raw) To: Eric Sunshine; +Cc: git, Marc-André Lureau On 12/11, Eric Sunshine wrote: > When worktree functionality was originally implemented, the possibility > of 'clone --local' from within a worktree was overlooked, with the > result that the location of the "objects" directory of the source > repository was computed incorrectly, thus the objects could not be > copied or hard-linked by the clone. This shortcoming was addressed by > 744e469755 (clone: allow --local from a linked checkout, 2015-09-28). > > However, the related case of 'clone --shared' (despite being handled > only a few lines away from the 'clone --local' case) was not fixed by > 744e469755, with a similar result of the "objects" directory location > being incorrectly computed for insertion into the 'alternates' file. > Fix this. > > Reported-by: Marc-André Lureau <marcandre.lureau@gmail.com> > Signed-off-by: Eric Sunshine <sunshine@sunshineco.com> > --- > builtin/clone.c | 3 ++- > t/t2025-worktree-add.sh | 6 ++++++ > 2 files changed, 8 insertions(+), 1 deletion(-) > > diff --git a/builtin/clone.c b/builtin/clone.c > index b22845738a..6ad0ab3fa4 100644 > --- a/builtin/clone.c > +++ b/builtin/clone.c > @@ -452,7 +452,8 @@ static void clone_local(const char *src_repo, const char *dest_repo) > { > if (option_shared) { > struct strbuf alt = STRBUF_INIT; > - strbuf_addf(&alt, "%s/objects", src_repo); > + get_common_dir(&alt, src_repo); > + strbuf_addstr(&alt, "/objects"); If you wanted to do this in one function call you could either use 'strbuf_git_common_path()' or either 'strbuf_git_path()' or 'strbuf_repo_git_path()' which will do the proper path adjustments when working on a path which should be shared between worktrees (i.e. part of the common git dir). > add_to_alternates_file(alt.buf); > strbuf_release(&alt); > } else { > diff --git a/t/t2025-worktree-add.sh b/t/t2025-worktree-add.sh > index b5c47ac602..7395973318 100755 > --- a/t/t2025-worktree-add.sh > +++ b/t/t2025-worktree-add.sh > @@ -245,6 +245,12 @@ test_expect_success 'local clone from linked checkout' ' > ( cd here-clone && git fsck ) > ' > > +test_expect_success 'local clone --shared from linked checkout' ' > + git -C bare worktree add --detach ../baretree && > + git clone --local --shared baretree bare-clone && > + grep /bare/ bare-clone/.git/objects/info/alternates > +' > + > test_expect_success '"add" worktree with --no-checkout' ' > git worktree add --no-checkout -b swamp swamp && > ! test -e swamp/init.t && > -- > 2.15.1.502.gccaef8de57 > -- Brandon Williams ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] clone: support 'clone --shared' from a worktree 2017-12-12 0:18 ` Brandon Williams @ 2017-12-12 0:40 ` Eric Sunshine 2017-12-12 0:52 ` Brandon Williams 0 siblings, 1 reply; 8+ messages in thread From: Eric Sunshine @ 2017-12-12 0:40 UTC (permalink / raw) To: Brandon Williams; +Cc: Git List, Marc-André Lureau On Mon, Dec 11, 2017 at 7:18 PM, Brandon Williams <bmwill@google.com> wrote: > On 12/11, Eric Sunshine wrote: >> struct strbuf alt = STRBUF_INIT; >> - strbuf_addf(&alt, "%s/objects", src_repo); >> + get_common_dir(&alt, src_repo); >> + strbuf_addstr(&alt, "/objects"); > > If you wanted to do this in one function call you could either use > 'strbuf_git_common_path()' or either 'strbuf_git_path()' or > 'strbuf_repo_git_path()' which will do the proper path adjustments when > working on a path which should be shared between worktrees (i.e. part of > the common git dir). Thanks for the pointers, however, the above fix mirrors the fix made by 744e469755 (clone: allow --local from a linked checkout, 2015-09-28) to code immediately below it in the 'else' arm: get_common_dir(&src, src_repo); get_common_dir(&dest, dest_repo); strbuf_addstr(&src, "/objects"); strbuf_addstr(&dest, "/objects"); It would be poor form and confusing to use one of the mechanisms you suggest while leaving the 'else' arm untouched. Re-working both arms of the 'if' to use one of the suggested functions would make a fine follow-on or preparatory patch, however, I'd rather not hold up this fix merely to re-roll for such a minor cleanup. (I also considered a follow-on patch to reduce the duplication between the two cases but decided against it, for the present, since such a patch would almost be noise without much gain.) By the way, is there any documentation explaining the differences between all these similar functions and when one should be used over the others? ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] clone: support 'clone --shared' from a worktree 2017-12-12 0:40 ` Eric Sunshine @ 2017-12-12 0:52 ` Brandon Williams 2017-12-13 18:28 ` [PATCH] path: document path functions Brandon Williams 0 siblings, 1 reply; 8+ messages in thread From: Brandon Williams @ 2017-12-12 0:52 UTC (permalink / raw) To: Eric Sunshine; +Cc: Git List, Marc-André Lureau On 12/11, Eric Sunshine wrote: > On Mon, Dec 11, 2017 at 7:18 PM, Brandon Williams <bmwill@google.com> wrote: > > On 12/11, Eric Sunshine wrote: > >> struct strbuf alt = STRBUF_INIT; > >> - strbuf_addf(&alt, "%s/objects", src_repo); > >> + get_common_dir(&alt, src_repo); > >> + strbuf_addstr(&alt, "/objects"); > > > > If you wanted to do this in one function call you could either use > > 'strbuf_git_common_path()' or either 'strbuf_git_path()' or > > 'strbuf_repo_git_path()' which will do the proper path adjustments when > > working on a path which should be shared between worktrees (i.e. part of > > the common git dir). > > Thanks for the pointers, however, the above fix mirrors the fix made > by 744e469755 (clone: allow --local from a linked checkout, > 2015-09-28) to code immediately below it in the 'else' arm: > > get_common_dir(&src, src_repo); > get_common_dir(&dest, dest_repo); > strbuf_addstr(&src, "/objects"); > strbuf_addstr(&dest, "/objects"); > > It would be poor form and confusing to use one of the mechanisms you > suggest while leaving the 'else' arm untouched. > > Re-working both arms of the 'if' to use one of the suggested functions > would make a fine follow-on or preparatory patch, however, I'd rather > not hold up this fix merely to re-roll for such a minor cleanup. (I > also considered a follow-on patch to reduce the duplication between > the two cases but decided against it, for the present, since such a > patch would almost be noise without much gain.) I didn't look close enough at what you were trying to fix, you're right I think what you have here is good as the alternative would require a lot more reworking I think (at least to change the above part too). Either way though, I'm a little worried about what happens if you have GIT_COMMON_DIR set because then both the src and dest repo would share a common dir, I don't know if that is expected or not. Maybe something else to consider later. > > By the way, is there any documentation explaining the differences > between all these similar functions and when one should be used over > the others? I wish, I probably should have done a better job documenting it all in path.h when I added the repo_* flavor of functions. I'll add that to my list of things to do though :) -- Brandon Williams ^ permalink raw reply [flat|nested] 8+ messages in thread
* [PATCH] path: document path functions 2017-12-12 0:52 ` Brandon Williams @ 2017-12-13 18:28 ` Brandon Williams 2017-12-13 19:14 ` Junio C Hamano 2017-12-20 8:58 ` Eric Sunshine 0 siblings, 2 replies; 8+ messages in thread From: Brandon Williams @ 2017-12-13 18:28 UTC (permalink / raw) To: git; +Cc: sunshine, Brandon Williams Signed-off-by: Brandon Williams <bmwill@google.com> --- As promised here is an update to the documentation for the path generating functions. path.h | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 112 insertions(+), 21 deletions(-) diff --git a/path.h b/path.h index 9541620c7..1ccd0373c 100644 --- a/path.h +++ b/path.h @@ -4,53 +4,144 @@ struct repository; /* - * Return a statically allocated filename, either generically (mkpath), in - * the repository directory (git_path), or in a submodule's repository - * directory (git_path_submodule). In all cases, note that the result - * may be overwritten by another call to _any_ of the functions. Consider - * using the safer "dup" or "strbuf" formats below (in some cases, the - * unsafe versions have already been removed). + * The result to all functions which return statically allocated memory may be + * overwritten by another call to _any_ one of these functions. Consider using + * the safer variants which operate on strbufs or return allocated memory. */ -extern const char *mkpath(const char *fmt, ...) __attribute__((format (printf, 1, 2))); -extern const char *git_path(const char *fmt, ...) __attribute__((format (printf, 1, 2))); -extern const char *git_common_path(const char *fmt, ...) __attribute__((format (printf, 1, 2))); +/* + * Return a statically allocated path. + */ +extern const char *mkpath(const char *fmt, ...) + __attribute__((format (printf, 1, 2))); + +/* + * Return a path. + */ +extern char *mkpathdup(const char *fmt, ...) + __attribute__((format (printf, 1, 2))); + +/* + * Construct a path and place the result in the provided buffer `buf`. + */ extern char *mksnpath(char *buf, size_t n, const char *fmt, ...) __attribute__((format (printf, 3, 4))); -extern void strbuf_git_path(struct strbuf *sb, const char *fmt, ...) - __attribute__((format (printf, 2, 3))); + +/* + * The `git_common_path` family of functions will construct a path into a + * repository's common git directory, which is shared by all worktrees. + */ + +/* + * Constructs a path into the common git directory of repository `repo` and + * append it in the provided buffer `sb`. + */ extern void strbuf_git_common_path(struct strbuf *sb, const struct repository *repo, const char *fmt, ...) __attribute__((format (printf, 3, 4))); -extern char *git_path_buf(struct strbuf *buf, const char *fmt, ...) - __attribute__((format (printf, 2, 3))); -extern int strbuf_git_path_submodule(struct strbuf *sb, const char *path, - const char *fmt, ...) - __attribute__((format (printf, 3, 4))); -extern char *git_pathdup(const char *fmt, ...) - __attribute__((format (printf, 1, 2))); -extern char *mkpathdup(const char *fmt, ...) + +/* + * Return a statically allocated path into the main repository's + * (the_repository) common git directory. + */ +extern const char *git_common_path(const char *fmt, ...) __attribute__((format (printf, 1, 2))); -extern char *git_pathdup_submodule(const char *path, const char *fmt, ...) - __attribute__((format (printf, 2, 3))); + +/* + * The `git_path` family of functions will construct a path into a repository's + * git directory. + * + * These functions will perform adjustments to the resultant path to account + * for special paths which are either considered common among worktrees (e.g. + * paths into the object directory) or have been explicitly set via an + * environment variable or config (e.g. path to the index file). + * + * For an exhaustive list of the adjustments made look at `common_list` and + * `adjust_git_path` in path.c. + */ + +/* + * Return a path into the git directory of repository `repo`. + */ extern char *repo_git_path(const struct repository *repo, const char *fmt, ...) __attribute__((format (printf, 2, 3))); + +/* + * Construct a path into the git directory of repository `repo` and append it + * to the provided buffer `sb`. + */ extern void strbuf_repo_git_path(struct strbuf *sb, const struct repository *repo, const char *fmt, ...) __attribute__((format (printf, 3, 4))); +/* + * Return a statically allocated path into the main repository's + * (the_repository) git directory. + */ +extern const char *git_path(const char *fmt, ...) + __attribute__((format (printf, 1, 2))); + +/* + * Return a path into the main repository's (the_repository) git directory. + */ +extern char *git_pathdup(const char *fmt, ...) + __attribute__((format (printf, 1, 2))); + +/* + * Construct a path into the main repository's (the_repository) git directory + * and place it in the provided buffer `buf`, the contents of the buffer will + * be overridden. + */ +extern char *git_path_buf(struct strbuf *buf, const char *fmt, ...) + __attribute__((format (printf, 2, 3))); + +/* + * Construct a path into the main repository's (the_repository) git directory + * and append it to the provided buffer `sb`. + */ +extern void strbuf_git_path(struct strbuf *sb, const char *fmt, ...) + __attribute__((format (printf, 2, 3))); + +/* + * Return a path into the worktree of repository `repo`. + * + * If the repository doesn't have a worktree NULL is returned. + */ extern char *repo_worktree_path(const struct repository *repo, const char *fmt, ...) __attribute__((format (printf, 2, 3))); + +/* + * Construct a path into the worktree of repository `repo` and append it + * to the provided buffer `sb`. + * + * If the repository doesn't have a worktree nothing will be appended to `sb`. + */ extern void strbuf_repo_worktree_path(struct strbuf *sb, const struct repository *repo, const char *fmt, ...) __attribute__((format (printf, 3, 4))); +/* + * Return a path into a submodule's git directory located at `path`. `path` + * must only reference a submodule of the main repository (the_repository). + */ +extern char *git_pathdup_submodule(const char *path, const char *fmt, ...) + __attribute__((format (printf, 2, 3))); + +/* + * Construct a path into a submodule's git directory located at `path` and + * append it to the provided buffer `sb`. `path` must only reference a + * submodule of the main repository (the_repository). + */ +extern int strbuf_git_path_submodule(struct strbuf *sb, const char *path, + const char *fmt, ...) + __attribute__((format (printf, 3, 4))); + extern void report_linked_checkout_garbage(void); /* -- 2.15.1.504.g5279b80103-goog ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH] path: document path functions 2017-12-13 18:28 ` [PATCH] path: document path functions Brandon Williams @ 2017-12-13 19:14 ` Junio C Hamano 2017-12-20 8:58 ` Eric Sunshine 1 sibling, 0 replies; 8+ messages in thread From: Junio C Hamano @ 2017-12-13 19:14 UTC (permalink / raw) To: Brandon Williams; +Cc: git, sunshine Brandon Williams <bmwill@google.com> writes: > Signed-off-by: Brandon Williams <bmwill@google.com> > --- > > As promised here is an update to the documentation for the path generating > functions. > > path.h | 133 ++++++++++++++++++++++++++++++++++++++++++++++++++++++----------- > 1 file changed, 112 insertions(+), 21 deletions(-) > > diff --git a/path.h b/path.h > index 9541620c7..1ccd0373c 100644 > --- a/path.h > +++ b/path.h > @@ -4,53 +4,144 @@ > struct repository; > > /* > - * Return a statically allocated filename, either generically (mkpath), in > - * the repository directory (git_path), or in a submodule's repository > - * directory (git_path_submodule). In all cases, note that the result > - * may be overwritten by another call to _any_ of the functions. Consider > - * using the safer "dup" or "strbuf" formats below (in some cases, the > - * unsafe versions have already been removed). > + * The result to all functions which return statically allocated memory may be > + * overwritten by another call to _any_ one of these functions. Consider using > + * the safer variants which operate on strbufs or return allocated memory. > */ The result of the update definitely is better, but stepping back a bit, it still does not answer some questions the original did not: - is the resulting path absolute? if relative, relative to what (cwd)? - what should a caller write in fmt? can we have a couple of typical calling example? - does a caller need to know which hierarchies under $GIT_DIR are common and call git_common_path() for them, or does git_path() do the 'right' thing for the caller? If latter, what's the use of git_common_path() for callers (outside the implementation of path.c API)? Will queue. Thanks. ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH] path: document path functions 2017-12-13 18:28 ` [PATCH] path: document path functions Brandon Williams 2017-12-13 19:14 ` Junio C Hamano @ 2017-12-20 8:58 ` Eric Sunshine 1 sibling, 0 replies; 8+ messages in thread From: Eric Sunshine @ 2017-12-20 8:58 UTC (permalink / raw) To: Brandon Williams; +Cc: Git List, Junio C Hamano On Wed, Dec 13, 2017 at 1:28 PM, Brandon Williams <bmwill@google.com> wrote: > As promised here is an update to the documentation for the path generating > functions. Thanks for working on this. Aside from the review comments by Junio[1], see a few more below. Although I had some familiarity with the non-repo versions of these functions a couple year ago when working on git-worktree, I've since forgotten much of it, so take my comments as if from someone trying to learn this API from scratch (which is effectively what I'm doing again). In particular, as I read this patch, I find that I still have to consult the source code (path.c) to figure out what some of these functions are for or what they do. [1]: https://public-inbox.org/git/xmqqr2rywid7.fsf@gitster.mtv.corp.google.com/ > diff --git a/path.h b/path.h > @@ -4,53 +4,144 @@ > /* > + * The result to all functions which return statically allocated memory may be > + * overwritten by another call to _any_ one of these functions. Consider using > + * the safer variants which operate on strbufs or return allocated memory. > */ > > +/* > + * Return a statically allocated path. > + */ > +extern const char *mkpath(const char *fmt, ...) > + __attribute__((format (printf, 1, 2))); It's not, at first glance, clear what benefit this function provides over simply constructing a path manually with, say, sprintf() or strbuf. Should this mention that a certain amount of normalization is performed on the path? Furthermore, perhaps the comment block above which talks about "statically allocated memory" could do a better job of conveying that these functions rid the caller of the responsibility of managing string storage itself. I wonder if it also might make sense to mention that the returned path won't necessarily be overwritten by the very next call (or is that an implementation detail we'd rather people not rely upon?). > +/* > + * Return a path. > + */ > +extern char *mkpathdup(const char *fmt, ...) > + __attribute__((format (printf, 1, 2))); I realize that it's implied by "dup", but perhaps the documentation should state explicitly that the caller is responsible for freeing the result? > +/* > + * The `git_common_path` family of functions will construct a path into a > + * repository's common git directory, which is shared by all worktrees. > + */ My first question when reading this was "What is a common git directory? (Is that where a bunch of repositories live or what?)". I suppose if it had said "common .git/ directory", it would have been clearer. Perhaps mentioning GIT_DIR might help clarify it, as well. ...repository's common .git/ directory (or $GIT_DIR), which is shared by all worktrees. > +/* > + * Constructs a path into the common git directory of repository `repo` and > + * append it in the provided buffer `sb`. > + */ > extern void strbuf_git_common_path(struct strbuf *sb, > const struct repository *repo, > const char *fmt, ...) > __attribute__((format (printf, 3, 4))); It's nice that this states explicitly that it _appends_ rather than overwrites. So often, one has to consult the implementation to determine the actual behavior. Perhaps I'm simple-minded, but at this point in the read, the concept of "common git directory" still feels nebulous. If the documentation presented even a simple example of how this is used (such as, for instance, calling this function to obtain ".git/HEAD"), it would help make the concept more concrete. Or, perhaps the example could be presented in the comment block just above which talks about this family of functions. > +/* > + * Return a statically allocated path into the main repository's > + * (the_repository) common git directory. > + */ > +extern const char *git_common_path(const char *fmt, ...) > __attribute__((format (printf, 1, 2))); I suppose that other repositories would be submodules? Would it make sense to mention something about that to clue in readers? Return a statically allocated path into the common .git/ directory of the main repository (not a submodule repository). Or something. Aside: After reading "main repository" here and seeing the 'repo' variants below, one wonders why the corresponding repo_git_common_path() doesn't exist. (Just an idle question; not actionable, and outside the scope of this patch.) > +/* > + * The `git_path` family of functions will construct a path into a repository's > + * git directory. > + * > + * These functions will perform adjustments to the resultant path to account > + * for special paths which are either considered common among worktrees (e.g. > + * paths into the object directory) or have been explicitly set via an > + * environment variable or config (e.g. path to the index file). > + * > + * For an exhaustive list of the adjustments made look at `common_list` and > + * `adjust_git_path` in path.c. > + */ I feel somewhat clueless after reading this. It doesn't necessarily give enough information for the reader to understand when or why these functions should be used as opposed to one of the functions described earlier. This may be due to it not stating early enough or forcefully enough that the location of certain files is not fixed, that they reside elsewhere when worktrees are involved. Perhaps something along these lines would help make it more concrete: Administrative files within .git/ may reside at different locations depending upon whether worktrees are involved. Some files and directories are common to all worktrees (for instance, ".git/hooks", ".git/objects") but others are localized to the main directory or to each worktree (for instance, ".git/HEAD" vs ".git/worktrees/<id>/HEAD). Other factors, such as environment variables or configuration settings may also impact locations of administrative files. The 'git_path' family of functions employs specialized knowledge of these issues when constructing a path to an administrative file or directory, thus relieving the caller of the burden of manually figuring out where resources reside. > +/* > + * Return a path into the git directory of repository `repo`. > + */ > extern char *repo_git_path(const struct repository *repo, > const char *fmt, ...) > __attribute__((format (printf, 2, 3))); I presume by the return type that the caller is responsible for freeing the result. Perhaps the documentation can state that explicitly. > +/* > + * Return a path into the main repository's (the_repository) git directory. > + */ > +extern char *git_pathdup(const char *fmt, ...) > + __attribute__((format (printf, 1, 2))); Perhaps mention that the caller is responsible for freeing the result. > +/* > + * Construct a path into the main repository's (the_repository) git directory > + * and place it in the provided buffer `buf`, the contents of the buffer will > + * be overridden. s/overridden/overwritten/ > + */ > +extern char *git_path_buf(struct strbuf *buf, const char *fmt, ...) > + __attribute__((format (printf, 2, 3))); Nice to see that this explains that the buffer will be overwritten (as opposed to appended). This function is a less flexible special case of strbuf_git_path() below. Does this mean it is deprecated? Should the documentation say something about preferring strbuf_git_path() instead? > +/* > + * Construct a path into the main repository's (the_repository) git directory > + * and append it to the provided buffer `sb`. > + */ > +extern void strbuf_git_path(struct strbuf *sb, const char *fmt, ...) > + __attribute__((format (printf, 2, 3))); > + > +/* > + * Return a path into the worktree of repository `repo`. > + * > + * If the repository doesn't have a worktree NULL is returned. > + */ > extern char *repo_worktree_path(const struct repository *repo, > const char *fmt, ...) > __attribute__((format (printf, 2, 3))); Now this is getting confusing. The documentation for the 'git_path' family of functions said that it takes worktrees into consideration. So what precisely do the 'worktree_path' family of functions do? When does one use them over the 'git_path' family? Also, caller is responsible for freeing result. > +/* > + * Return a path into a submodule's git directory located at `path`. `path` > + * must only reference a submodule of the main repository (the_repository). > + */ Ouch, ambiguity hurts my brain. Does this mean that the submodule is located at 'path' or that the .git/ directory is located at 'path'? Perhaps: Return a path into the .git/ directory of a submodule located at 'path'. ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2017-12-20 8:58 UTC | newest] Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2017-12-11 23:16 [PATCH] clone: support 'clone --shared' from a worktree Eric Sunshine 2017-12-12 0:01 ` Junio C Hamano 2017-12-12 0:18 ` Brandon Williams 2017-12-12 0:40 ` Eric Sunshine 2017-12-12 0:52 ` Brandon Williams 2017-12-13 18:28 ` [PATCH] path: document path functions Brandon Williams 2017-12-13 19:14 ` Junio C Hamano 2017-12-20 8:58 ` Eric Sunshine
Code repositories for project(s) associated with this public inbox https://80x24.org/mirrors/git.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).