Update git-clone doc: refer to long form of the options and list short form of the options first #277
Conversation
Welcome to GitGitGadgetHi @kenden, and welcome to GitGitGadget, the GitHub App to send patch series to the Git mailing list from GitHub Pull Requests. Please make sure that this Pull Request has a good description, as it will be used as cover letter. Also, it is a good idea to review the commit messages one last time, as the Git project expects them in a quite specific form:
It is in general a good idea to await the automated test ("Checks") in this Pull Request before contributing the patches, e.g. to avoid trivial issues such as unportable code. Contributing the patchesBefore you can contribute the patches, your GitHub username needs to be added to the list of permitted users. Any already-permitted user can do that, by adding a PR comment of the form Once on the list of permitted usernames, you can contribute the patches to the Git mailing list by adding a PR comment After you submit, GitGitGadget will respond with another comment that contains the link to the cover letter mail in the Git mailing list archive. Please make sure to monitor the discussion in that thread and to address comments and suggestions. If you do not want to subscribe to the Git mailing list just to be able to respond to a mail, you can download the mbox ("raw") file corresponding to the mail you want to reply to from the Git mailing list. If you use GMail, you can upload that raw mbox file via: curl -g --user "<EMailAddress>:<Password>" --url "imaps://imap.gmail.com/INBOX" -T /path/to/raw.txt |
|
/allow kenden |
|
User kenden is now allowed to use GitGitGadget. |
|
/submit |
|
Submitted as [email protected] |
![gitgitgadget[bot]](https://avatars.githubusercontent.com/in/12836?s=60&v=4){kind=small}
| @@ -41,8 +41,8 @@ configuration variables. | |||
|
|
|||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
Thanks, I re-submitted with two different commits.
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 <[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]>
kenden
changed the title
|
/submit |
|
Submitted as [email protected] |
| @@ -23,7 +23,7 @@ DESCRIPTION | |||
|
|
|||
There was a problem hiding this comment.
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.
|
This branch is now known as |
|
This patch series was integrated into pu via git@882a84c. |
|
This patch series was integrated into pu via git@6b8ce0c. |
|
This patch series was integrated into pu via git@2b819e0. |
|
This patch series was integrated into pu via git@14e91b6. |
|
This patch series was integrated into next via git@b2e1880. |
|
This patch series was integrated into pu via git@4ad01a4. |
|
This patch series was integrated into next via git@4ad01a4. |
|
This patch series was integrated into master via git@4ad01a4. |
|
Closed via 4ad01a4. |
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...