Subject: Re: [GSoC] [PATCH v2 4/9] dir: libify and export helper functions from clone.c

From: Junio C Hamano <[email-masked]>
Date: Thu, 05 Aug 2021 13:37:10 -0700

Atharva Raykar <[email-masked]> writes:

> These functions can be useful to other parts of Git. Let's move them to
> dir.c, while renaming them to be make their functionality more explicit.

Hmph, guess_dir_name_from_git_url() is not all that more clarifying
than the original, at least to me.  For a file-scope static helper,
it probably was good enough with a short name with no function doc,
but we should describe what it does in comments in dir.h and come up
with a suitable name, taking input from that description.

> Signed-off-by: Atharva Raykar <[email-masked]>
> Mentored-by: Christian Couder <[email-masked]>
> Mentored-by: Shourya Shukla <[email-masked]>
> ---
>  builtin/clone.c | 118 +-----------------------------------------------
>  dir.c           | 114 ++++++++++++++++++++++++++++++++++++++++++++++
>  dir.h           |   3 ++
>  3 files changed, 119 insertions(+), 116 deletions(-)

Again "show --color-moved" helps to see that these two helper
functions are moved across files without any change other than the
names, which is good.

> @@ -1041,8 +927,8 @@ int cmd_clone(int argc, const char **argv, const char *prefix)
>  	if (argc == 2)
>  		dir = xstrdup(argv[1]);
>  	else
> -		dir = guess_dir_name(repo_name, is_bundle, option_bare);
> -	strip_trailing_slashes(dir);
> +		dir = guess_dir_name_from_git_url(repo_name, is_bundle, option_bare);
> +	strip_dir_trailing_slashes(dir);

So, what does this new public helper function guess?  The name of
the function says it guesses a directory name, but it is not just
any directory name, but a directory with some specific meaning.

Here repo_name has the URL the user gave "git clone", and even
though there are some code before this part that computed on the
variable, it hasn't been modified.  And "from_git_url" is a good way
to indicate that that is one of the input the function uses to guess
the name of "the directory with some unknown specific meaning".

I think this codepath wants the new directory to create as the
result of "git clone" operation in "dir".  So, even though I still
do not have a good answer to the earlier "this is not just any
directory but with some specific meaning---what is it?" question,
adjectives that are appropriate for the "directory" to answer it
may be along the lines of "new", "resulting", "cloned", etc.

> diff --git a/dir.h b/dir.h
> index b3e1a54a97..76441dde2d 100644
> --- a/dir.h
> +++ b/dir.h
> @@ -453,6 +453,9 @@ static inline int is_dot_or_dotdot(const char *name)
>  
>  int is_empty_dir(const char *dir);
>  

We would want docstring here for the function (and possibly rename
the function to clarify what kind of "dir" we are talking about).

> +char *guess_dir_name_from_git_url(const char *repo, int is_bundle, int is_bare);
> +void strip_dir_trailing_slashes(char *dir);
> +
>  void setup_standard_excludes(struct dir_struct *dir);
>  
>  char *get_sparse_checkout_filename(void);

Thanks.