From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 27 Jun 2019 20:10:51 GMT
Subject: Re: [PATCH 1/1] docs: update git-clone doc: refer to long options
Message-ID: <xmqqmui2aiwk.fsf@gitster-ct.c.googlers.com>
In-Reply-To: <0dd1b017698dd9d15f291f1133eb40dac8d85a68.1561663019.git.gitgitgadget@gmail.com>

"Quentin Nerden via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Quentin Nerden <quentin.nerden@gmail.com>
>
> To make the doc of git-clone easier to read,
> refer to the long version of the options
> (it is easier to guess what --verbose is doing than -v).
>
> Also:
> put the short options first, to match the doc of git-add, git-commit, git-clean, git-branch...

This "also" makes the patch unnecessarily harder to review.
Splitting it into two patches would make it reviewable.

Thanks.

>
> Signed-off-by: Quentin Nerden <quentin.nerden@gmail.com>
> ---
>  Documentation/git-clone.txt | 28 ++++++++++++++--------------
>  1 file changed, 14 insertions(+), 14 deletions(-)
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index 5fc97f14de..4edc713a4b 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -41,8 +41,8 @@ configuration variables.
>  
>  OPTIONS
>  -------
> ---local::
>  -l::
> +--local::
>  	When the repository to clone from is on a local machine,
>  	this flag bypasses the normal "Git aware" transport
>  	mechanism and clones the repository by making a copy of
> @@ -63,8 +63,8 @@ Git transport instead.
>  	directory instead of using hardlinks. This may be desirable
>  	if you are trying to make a back-up of your repository.
>  
> ---shared::
>  -s::
> +--shared::
>  	When the repository to clone is on the local machine,
>  	instead of using hard links, automatically setup
>  	`.git/objects/info/alternates` to share the objects
> @@ -81,10 +81,10 @@ which automatically call `git gc --auto`. (See linkgit:git-gc[1].)
>  If these objects are removed and were referenced by the cloned repository,
>  then the cloned repository will become corrupt.
>  +
> -Note that running `git repack` without the `-l` option in a repository
> +Note that running `git repack` without the `--local` option in a repository
>  cloned with `-s` will copy objects from the source repository into a pack
>  in the cloned repository, removing the disk space savings of `clone -s`.
> -It is safe, however, to run `git gc`, which uses the `-l` option by
> +It is safe, however, to run `git gc`, which uses the `--local` option by
>  default.
>  +
>  If you want to break the dependency of a repository cloned with `-s` on
> @@ -116,19 +116,19 @@ objects from the source repository into a pack in the cloned repository.
>  	same repository, and this option can be used to stop the
>  	borrowing.
>  
> ---quiet::
>  -q::
> +--quiet::
>  	Operate quietly.  Progress is not reported to the standard
>  	error stream.
>  
> ---verbose::
>  -v::
> +--verbose::
>  	Run verbosely. Does not affect the reporting of progress status
>  	to the standard error stream.
>  
>  --progress::
>  	Progress status is reported on the standard error stream
> -	by default when it is attached to a terminal, unless -q
> +	by default when it is attached to a terminal, unless `--quiet`
>  	is specified. This flag forces progress status even if the
>  	standard error stream is not directed to a terminal.
>  
> @@ -140,15 +140,15 @@ objects from the source repository into a pack in the cloned repository.
>  	When multiple `--server-option=<option>` are given, they are all
>  	sent to the other side in the order listed on the command line.
>  
> ---no-checkout::
>  -n::
> +--no-checkout::
>  	No checkout of HEAD is performed after the clone is complete.
>  
>  --bare::
>  	Make a 'bare' Git repository.  That is, instead of
>  	creating `<directory>` and placing the administrative
>  	files in `<directory>/.git`, make the `<directory>`
> -	itself the `$GIT_DIR`. This obviously implies the `-n`
> +	itself the `$GIT_DIR`. This obviously implies `--no-checkout`
>  	because there is nowhere to check out the working tree.
>  	Also the branch heads at the remote are copied directly
>  	to corresponding local branch heads, without mapping
> @@ -164,13 +164,13 @@ objects from the source repository into a pack in the cloned repository.
>  	that all these refs are overwritten by a `git remote update` in the
>  	target repository.
>  
> ---origin <name>::
>  -o <name>::
> +--origin <name>::
>  	Instead of using the remote name `origin` to keep track
>  	of the upstream repository, use `<name>`.
>  
> ---branch <name>::
>  -b <name>::
> +--branch <name>::
>  	Instead of pointing the newly created HEAD to the branch pointed
>  	to by the cloned repository's HEAD, point to `<name>` branch
>  	instead. In a non-bare repository, this is the branch that will
> @@ -178,8 +178,8 @@ objects from the source repository into a pack in the cloned repository.
>  	`--branch` can also take tags and detaches the HEAD at that commit
>  	in the resulting repository.
>  
> ---upload-pack <upload-pack>::
>  -u <upload-pack>::
> +--upload-pack <upload-pack>::
>  	When given, and the repository to clone from is accessed
>  	via ssh, this specifies a non-default path for the command
>  	run on the other end.
> @@ -188,8 +188,8 @@ objects from the source repository into a pack in the cloned repository.
>  	Specify the directory from which templates will be used;
>  	(See the "TEMPLATE DIRECTORY" section of linkgit:git-init[1].)
>  
> ---config <key>=<value>::
>  -c <key>=<value>::
> +--config <key>=<value>::
>  	Set a configuration variable in the newly-created repository;
>  	this takes effect immediately after the repository is
>  	initialized, but before the remote history is fetched or any
> @@ -274,8 +274,8 @@ or `--mirror` is given)
>  	The result is Git repository can be separated from working
>  	tree.
>  
> --j <n>::
>  --jobs <n>::
> +-j <n>::
>  	The number of submodules fetched at the same time.
>  	Defaults to the `submodule.fetchJobs` option.