Re: [PATCH] git: update documentation for --git-dir

From: Junio C Hamano <gitster@pobox.com>
Date: Jan 23, 2020, 06:41 UTC
Message-ID: <xmqq1rrq65ed.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <pull.537.git.1579745811615.gitgitgadget@gmail.com>

"Heba Waly via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 6 quoted lines

>  --git-dir=<path>::
> -	Set the path to the repository. This can also be controlled by
> -	setting the `GIT_DIR` environment variable. It can be an absolute
> -	path or relative path to current working directory.
> -
> +	Set the path to the repository (i.e. the .git folder). This can also be

I suspect (i.e. ".git") may be clear enough, but if you must, say ".git directory", not ".git folder", as you mention "current working directory" later.

> +	controlled by setting the `GIT_DIR` environment variable. It can be
> +	an absolute path or relative path to current working directory.
> +
> +	Note that --git-dir=<path> is not the same as -C=<path>.

Surely, of course.

> +	It's preferrable to set --work-tree=<path> as well when setting
> +	--git-dir to make sure Git will run your command across the correct
> +	work tree.

It does not help the readers that much to say "It's preferrable" without saying what negative implications there are if they don't use it, or what positive effect they would observe if they do.

If I were writing it, I'd drop "Note that..." and rewrite the three lines more like...

	Specifying the location of the ".git" directory using this
	option (or GIT_DIR environment variable) turns off the
	repository discovery that tries to find a directory with
	".git" subdirectory (which is how the repository and the
	top-level of the working tree are discovered), and tells Git
	that you are at the top level of the working tree.  If you
	are not at the top-level directory of the working tree, you
	should tell Git where the top-level of the working tree is,
	with the --work-tree=<path> option (or GIT_WORK_TREE
	environment variable)

perhaps.

Show 5 quoted lines

>  --work-tree=<path>::
>  	Set the path to the working tree. It can be an absolute path
>  	or a path relative to the current working directory.
>
> base-commit: 232378479ee6c66206d47a9be175e3a39682aea6

I do not know if GGG users have control over this, but I'd prefer to see a "-- " divider before this "base-commit: ..." footer material.