Update git-clone doc: refer to long option
cover Update git-clone doc: refer to long option
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
Signature · 1 line
gitgitgadget
PATCH 1/1 docs: update git-clone doc: refer to long options
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...
--- Documentation/git-clone.txt | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-)
Documentation/git-clone.txt +14 -14
@@ -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.
Signature · 1 line
gitgitgadget
Re: [PATCH 1/1] docs: update git-clone doc: refer to long options
Quoted 8 lines · Quentin Nerden via GitGitGadget
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.
Quoted 129 lines
Signed-off-by Quentin Nerden <[email protected]>--- Documentation/git-clone.txt | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-)Documentation/git-clone.txt +14
-14@@ -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
Hi,
Quoted 8 lines · Junio C Hamano
Quoted 6 lines · Quentin Nerden via GitGitGadget
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).
Quoted 5 lines
Quoted 2 lines
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 1/2 docs: git-clone: refer to long form of options
In reply to Quentin Nerden via GitGitGadgetFrom: Quentin Nerden <[email protected]>
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').
--- Documentation/git-clone.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-)
Documentation/git-clone.txt +8 -8
@@ -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
Signature · 1 line
gitgitgadget
PATCH v2 2/2 docs: git-clone: list short form of options first
In reply to Quentin Nerden via GitGitGadgetFrom: 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...
--- Documentation/git-clone.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-)
Documentation/git-clone.txt +9 -9
@@ -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
Signature · 1 line
gitgitgadget
v2 cover Update git-clone doc: refer to long form of the options and list short form of the options first
In reply to Quentin Nerden via GitGitGadgetTo 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 <[email protected]> +Author: Quentin Nerden <[email protected]>
- 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...
@@ -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.
-
Signature · 1 line
gitgitgadget
Re: [PATCH v2 2/2] docs: git-clone: list short form of options first
In reply to Quentin Nerden via GitGitGadgetQuoted 10 lines · Quentin Nerden via GitGitGadget
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.