[PATCH 0/1] Update git-clone doc: refer to long option

[PATCH 0/1] Update git-clone doc: refer to long option

[Quentin Nerden via GitGitGadget]

To make 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...

Quentin Nerden (1):
  docs: update git-clone doc: refer to long options

 Documentation/git-clone.txt | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)


base-commit: 8dca754b1e874719a732bc9ab7b0e14b21b1bc10
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-277%2Fkenden%2Fpatch-1-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-277/kenden/patch-1-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/277
-- 
gitgitgadget

[PATCH 1/1] docs: update git-clone doc: refer to long options

[Quentin Nerden via GitGitGadget]

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...

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.
 
-- 
gitgitgadget

Re: [PATCH 1/1] docs: update git-clone doc: refer to long options

[Junio C Hamano]

"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.

Re: [PATCH 1/1] docs: update git-clone doc: refer to long options

[Johannes Schindelin]

Hi,

On Thu, 27 Jun 2019, Junio C Hamano wrote:

> "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.

Good idea.

The easiest way I can think of would be to split by first undoing the
commit via `git reset --hard HEAD^` (don't worry, the commit graph is
still accessible via the reflog), then staging the parts of the patch that
put the short options first: `git checkout -p HEAD@{1}`. After that is
done, commit with a new commit message, then get the remainder of the
changes via `git cherry-pick HEAD@{2}` (by now, the original commit is no
longer `HEAD@{1}` because a new commit has been appended to the reflog).

Then force-push and submit a new iteration ;-)

Ciao,
Johannes

[PATCH v2 0/2] Update git-clone doc: refer to long form of the options and list short form of the options first

[Quentin Nerden via GitGitGadget]

To make 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...

Quentin Nerden (2):
  docs: git-clone: refer to long form of options
  docs: git-clone: list short form of options first

 Documentation/git-clone.txt | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)


base-commit: 8dca754b1e874719a732bc9ab7b0e14b21b1bc10
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-277%2Fkenden%2Fpatch-1-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-277/kenden/patch-1-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/277

Range-diff vs v1:

 -:  ---------- > 1:  d2f5540ea1 docs: git-clone: refer to long form of options
 1:  0dd1b01769 ! 2:  c562cf681f docs: update git-clone doc: refer to long options
     @@ -1,13 +1,10 @@
     -Author: Quentin Nerden <quentin.nerden@gmail.com>
     +Author: Quentin Nerden <quentin.nerden@intel.com>
      
     -    docs: update git-clone doc: refer to long options
     +    docs: git-clone: list short form of options first
      
     -    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...
     +    List the short form of options (e.g.: '-l') before the long form (e.g.
     +    '--local').
     +    This is to match the doc of git-add, git-commit, git-clean, git-branch...
      
          Signed-off-by: Quentin Nerden <quentin.nerden@gmail.com>
      
     @@ -34,19 +31,6 @@
       	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
     -@@
     - 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
      @@
       	same repository, and this option can be used to stop the
       	borrowing.
     @@ -63,13 +47,6 @@
       	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.
     - 
      @@
       	When multiple `--server-option=<option>` are given, they are all
       	sent to the other side in the order listed on the command line.
     @@ -80,14 +57,6 @@
       	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
      @@
       	that all these refs are overwritten by a `git remote update` in the
       	target repository.
     @@ -124,13 +93,3 @@
       	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
     -@@
     - 	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.
     - 

-- 
gitgitgadget

[PATCH v2 1/2] docs: git-clone: refer to long form of options

[Quentin Nerden via GitGitGadget]

From: Quentin Nerden <quentin.nerden@intel.com>

To make the doc of git-clone easier to read,
refer to the long form of the options
(it is easier to guess what '--verbose' is doing than '-v').

Signed-off-by: Quentin Nerden <quentin.nerden@gmail.com>
---
 Documentation/git-clone.txt | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 5fc97f14de..cb3cf7a0fb 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -23,7 +23,7 @@ DESCRIPTION
 
 Clones a repository into a newly created directory, creates
 remote-tracking branches for each branch in the cloned repository
-(visible using `git branch -r`), and creates and checks out an
+(visible using `git branch --remotes`), and creates and checks out an
 initial branch that is forked from the cloned repository's
 currently active branch.
 
@@ -81,13 +81,13 @@ 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
-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
+Note that running `git repack` without the `--local` option in a repository
+cloned with `--shared` will copy objects from the source repository into a pack
+in the cloned repository, removing the disk space savings of `clone --shared`.
+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
+If you want to break the dependency of a repository cloned with `--shared` on
 its source repository, you can simply run `git repack -a` to copy all
 objects from the source repository into a pack in the cloned repository.
 
@@ -128,7 +128,7 @@ objects from the source repository into a pack in the cloned repository.
 
 --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.
 
@@ -148,7 +148,7 @@ objects from the source repository into a pack in the cloned repository.
 	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 the `--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
-- 
gitgitgadget

[PATCH v2 2/2] docs: git-clone: list short form of options first

[Quentin Nerden via GitGitGadget]

From: Quentin Nerden <quentin.nerden@intel.com>

List the short form of options (e.g.: '-l') before the long form (e.g.
'--local').
This is to match the doc of git-add, git-commit, git-clean, git-branch...

Signed-off-by: Quentin Nerden <quentin.nerden@gmail.com>
---
 Documentation/git-clone.txt | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index cb3cf7a0fb..34011c2940 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
@@ -116,13 +116,13 @@ 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.
 
@@ -140,8 +140,8 @@ 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::
@@ -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
-- 
gitgitgadget

Re: [PATCH v2 2/2] docs: git-clone: list short form of options first

[Junio C Hamano]

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

> From: Quentin Nerden <quentin.nerden@intel.com>
>
> List the short form of options (e.g.: '-l') before the long form (e.g.
> '--local').
> This is to match the doc of git-add, git-commit, git-clean, git-branch...
>
> Signed-off-by: Quentin Nerden <quentin.nerden@gmail.com>
> ---
>  Documentation/git-clone.txt | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)

Much easier to follow ;-)  Thanks.