Skip to content

Update git-clone doc: refer to long form of the options and list short form of the options first #277

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Update git-clone doc: refer to long form of the options and list short form of the options first #277

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d2f5540
docs: git-clone: refer to long form of options
qnerden Jul 2, 2019
c562cf6
docs: git-clone: list short form of options first
qnerden Jul 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions Documentation/git-clone.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ DESCRIPTION

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Quentin Nerden via GitGitGadget" <[email protected]> writes:

> From: Quentin Nerden <[email protected]>
>
> 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 <[email protected]>
> ---
>  Documentation/git-clone.txt | 18 +++++++++---------
>  1 file changed, 9 insertions(+), 9 deletions(-)

Much easier to follow ;-)  Thanks.

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.

Expand All @@ -41,8 +41,8 @@ configuration variables.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Junio C Hamano wrote (reply to this):

"Quentin Nerden via GitGitGadget" <[email protected]> writes:

> From: Quentin Nerden <[email protected]>
>
> 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 <[email protected]>
> ---
>  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.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the Git mailing list, Johannes Schindelin wrote (reply to this):

Hi,

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

> "Quentin Nerden via GitGitGadget" <[email protected]> writes:
>
> > From: Quentin Nerden <[email protected]>
> >
> > 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

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, I re-submitted with two different commits.

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
Expand All @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand All @@ -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 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
Expand All @@ -164,22 +164,22 @@ 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
be checked out.
`--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.
Expand All @@ -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
Expand Down