[PATCH] --disassociate alias for --dissociate clone option

[PATCH] --disassociate alias for --dissociate clone option

[Matt Whiteley]

I find the new --dissociate option for clone very helpful but I have a
hard time with the spelling. It seems reasonable to have an alias since
one exists for --recursive.

[PATCH 1/2] clone: add disassociate alias to dissociate option

[Matt Whiteley]

Enable clone to accept alternate spelling for dissociate option. Add
alias to documentation following existing recursive/recurse-submodules
convention.

Signed-off-by: Matt Whiteley <mattwhiteley@gmail.com>
---
 Documentation/git-clone.txt | 3 ++-
 builtin/clone.c             | 2 ++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index f1f2a3f..0b4c1b2 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -12,7 +12,7 @@ SYNOPSIS
 'git clone' [--template=<template_directory>]
 	  [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
 	  [-o <name>] [-b <name>] [-u <upload-pack>] [--reference <repository>]
-	  [--dissociate] [--separate-git-dir <git dir>]
+	  [--dissociate | --disassociate] [--separate-git-dir <git dir>]
 	  [--depth <depth>] [--[no-]single-branch]
 	  [--recursive | --recurse-submodules] [--] <repository>
 	  [<directory>]
@@ -102,6 +102,7 @@ objects from the source repository into a pack in the cloned repository.
 `--dissociate` option.
 
 --dissociate::
+--disassociate::
 	Borrow the objects from reference repositories specified
 	with the `--reference` options only to reduce network
 	transfer and stop borrowing from them after a clone is made
diff --git a/builtin/clone.c b/builtin/clone.c
index 316c75d..7e193ae 100644
--- a/builtin/clone.c
+++ b/builtin/clone.c
@@ -97,6 +97,8 @@ static struct option builtin_clone_options[] = {
 		    N_("clone only one branch, HEAD or --branch")),
 	OPT_BOOL(0, "dissociate", &option_dissociate,
 		 N_("use --reference only while cloning")),
+	OPT_BOOL(0, "disassociate", &option_dissociate,
+		 N_("use --reference only while cloning")),
 	OPT_STRING(0, "separate-git-dir", &real_git_dir, N_("gitdir"),
 		   N_("separate git dir from working tree")),
 	OPT_STRING_LIST('c', "config", &option_config, N_("key=value"),
-- 
2.3.0

[PATCH 2/2] clone: Realign lines near disassociate option

[Matt Whiteley]

Fix long line splitting format while adding to builtin_clone_options.

Signed-off-by: Matt Whiteley <mattwhiteley@gmail.com>
---
 builtin/clone.c | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/builtin/clone.c b/builtin/clone.c
index 7e193ae..fd6bcf4 100644
--- a/builtin/clone.c
+++ b/builtin/clone.c
@@ -72,15 +72,15 @@ static struct option builtin_clone_options[] = {
 	OPT_BOOL(0, "mirror", &option_mirror,
 		 N_("create a mirror repository (implies bare)")),
 	OPT_BOOL('l', "local", &option_local,
-		N_("to clone from a local repository")),
+		 N_("to clone from a local repository")),
 	OPT_BOOL(0, "no-hardlinks", &option_no_hardlinks,
-		    N_("don't use local hardlinks, always copy")),
+		 N_("don't use local hardlinks, always copy")),
 	OPT_BOOL('s', "shared", &option_shared,
-		    N_("setup as shared repository")),
+		 N_("setup as shared repository")),
 	OPT_BOOL(0, "recursive", &option_recursive,
-		    N_("initialize submodules in the clone")),
+		 N_("initialize submodules in the clone")),
 	OPT_BOOL(0, "recurse-submodules", &option_recursive,
-		    N_("initialize submodules in the clone")),
+		 N_("initialize submodules in the clone")),
 	OPT_STRING(0, "template", &option_template, N_("template-directory"),
 		   N_("directory from which templates will be used")),
 	OPT_CALLBACK(0 , "reference", &option_reference, N_("repo"),
@@ -92,9 +92,9 @@ static struct option builtin_clone_options[] = {
 	OPT_STRING('u', "upload-pack", &option_upload_pack, N_("path"),
 		   N_("path to git-upload-pack on the remote")),
 	OPT_STRING(0, "depth", &option_depth, N_("depth"),
-		    N_("create a shallow clone of that depth")),
+		   N_("create a shallow clone of that depth")),
 	OPT_BOOL(0, "single-branch", &option_single_branch,
-		    N_("clone only one branch, HEAD or --branch")),
+		 N_("clone only one branch, HEAD or --branch")),
 	OPT_BOOL(0, "dissociate", &option_dissociate,
 		 N_("use --reference only while cloning")),
 	OPT_BOOL(0, "disassociate", &option_dissociate,
-- 
2.3.0

Re: [PATCH] --disassociate alias for --dissociate clone option

[Eric Sunshine]

On Fri, Feb 20, 2015 at 2:10 PM, Matt Whiteley <mattwhiteley@gmail.com> wrote:
> I find the new --dissociate option for clone very helpful but I have a
> hard time with the spelling. It seems reasonable to have an alias since
> one exists for --recursive.

You may be undermining your own argument for inclusion of a new
--dissociate option by citing the aliased "recursive" option.

git-clone's --recursive-submodules was added (see ccdd3da6) for
disambiguation long after --recursive; and not the other way around
with --recursive being more convenient or easier to remember or spell
than --recursive-submodules. The implication of ccdd3da6 is that
--recursive-submodules is favored over --recursive (and perhaps the
latter may some day be deprecated).

Re: [PATCH 1/2] clone: add disassociate alias to dissociate option

[Jeff King]

On Fri, Feb 20, 2015 at 11:10:22AM -0800, Matt Whiteley wrote:

> diff --git a/builtin/clone.c b/builtin/clone.c
> index 316c75d..7e193ae 100644
> --- a/builtin/clone.c
> +++ b/builtin/clone.c
> @@ -97,6 +97,8 @@ static struct option builtin_clone_options[] = {
>  		    N_("clone only one branch, HEAD or --branch")),
>  	OPT_BOOL(0, "dissociate", &option_dissociate,
>  		 N_("use --reference only while cloning")),
> +	OPT_BOOL(0, "disassociate", &option_dissociate,
> +		 N_("use --reference only while cloning")),

Should this second one be marked as OPT_HIDDEN? I do not think we need
to show both in "git clone --help".

-Peff

Re: [PATCH 1/2] clone: add disassociate alias to dissociate option

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> On Fri, Feb 20, 2015 at 11:10:22AM -0800, Matt Whiteley wrote:
>
>> diff --git a/builtin/clone.c b/builtin/clone.c
>> index 316c75d..7e193ae 100644
>> --- a/builtin/clone.c
>> +++ b/builtin/clone.c
>> @@ -97,6 +97,8 @@ static struct option builtin_clone_options[] = {
>>  		    N_("clone only one branch, HEAD or --branch")),
>>  	OPT_BOOL(0, "dissociate", &option_dissociate,
>>  		 N_("use --reference only while cloning")),
>> +	OPT_BOOL(0, "disassociate", &option_dissociate,
>> +		 N_("use --reference only while cloning")),
>
> Should this second one be marked as OPT_HIDDEN? I do not think we need
> to show both in "git clone --help".

For that matter, I am not sure why we want to add this synonym in
the first place.

http://www.merriam-webster.com/dictionary/dissociate

    : to end your relationship with or connection to someone or
    something : to separate (yourself) from someone or something

which is exactly what I wanted the option to achieve.

Re: [PATCH 1/2] clone: add disassociate alias to dissociate option

[Jeff King]

On Fri, Feb 20, 2015 at 11:13:47PM -0800, Junio C Hamano wrote:

> >>  	OPT_BOOL(0, "dissociate", &option_dissociate,
> >>  		 N_("use --reference only while cloning")),
> >> +	OPT_BOOL(0, "disassociate", &option_dissociate,
> >> +		 N_("use --reference only while cloning")),
> >
> > Should this second one be marked as OPT_HIDDEN? I do not think we need
> > to show both in "git clone --help".
> 
> For that matter, I am not sure why we want to add this synonym in
> the first place.
> 
> http://www.merriam-webster.com/dictionary/dissociate
> 
>     : to end your relationship with or connection to someone or
>     something : to separate (yourself) from someone or something
> 
> which is exactly what I wanted the option to achieve.

That is also the definition of disassociate. :) They are both equally
correct here, and some people tend to use one over the other:

  http://grammarist.com/usage/dissociate-disassociate/

So I don't think the spirit of the patch is wrong, in that sense. I am
open to the argument that we do not want to get in the habit of
providing every possible synonym, as it would clutter the interface.
This case is a bit more extreme; given the similarity of the two words,
it is easy to use the wrong one. But I do not personally care much
either way.

As a side note, while writing out an explanation of "--reference
--dissociate" recently, Michael (cc'd) and I noticed that it seems quite
verbose to have to specify both options.

By itself, --dissociate does nothing. It _could_ imply --reference (but
right now complains that --reference was not provided and turns itself
off). But if we were to have a single-option version of "reference and
dissociate", I do not think "--dissociate" is the best choice. By itself
it does not mean much (dissociate from _what_?).

I wonder if there is some better word that could become a synonym for
"--reference --dissociate". Maybe "--borrow", but that does not
necessarily carry the implication that the relationship ends as soon as
the clone is done. What is really happening is that we are reusing
objects in order to save bandwidth. Maybe "--reuse-from" would work?

I dunno. I am not extremely happy with any of the suggestions I made,
nor is any of this of extreme importance to me. But I thought I would
mention it while we are on the subject.

-Peff

Re: [PATCH 1/2] clone: add disassociate alias to dissociate option

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> I wonder if there is some better word that could become a synonym for
> "--reference --dissociate". Maybe "--borrow", but that does not
> necessarily carry the implication that the relationship ends as soon as
> the clone is done.

You are retracing the exact line of the thinking that led me to a
cop-out that is a separate "--dissociate".

The original idea was to give "--borrow /local/repository/path", but
that would have made it unclear what the differences between that
new option and existing "--reference" were.  Both borrow the objects
in order to reduce the network cost, and the difference is that one
keeps borrowing while the other one limits the borrowing to strictly
the initial phase.  The two words, "borrow" and "reference", would
not convey that key distinction.  "Do the reference thing (which is
well understood from old days, even before v1.6.0) and then severe
the ties" was suboptimal but was easy to explain, and that is why I
call it a cop-out.

> What is really happening is that we are reusing
> objects in order to save bandwidth. Maybe "--reuse-from" would work?
>
> I dunno. I am not extremely happy with any of the suggestions I made,...

I dunno, either.

We are all on the same page.  We know the cop-out is suboptimal, we
understand why the cop-out is better than "--borrow", and we cannot
come up with a better name that contrasts with the existing
"--reference" to make it clear how the new thing is different.

Re: [PATCH 1/2] clone: add disassociate alias to dissociate option

[Michael Haggerty]

On 02/22/2015 07:32 PM, Junio C Hamano wrote:
> Jeff King <peff@peff.net> writes:
> 
>> I wonder if there is some better word that could become a synonym for
>> "--reference --dissociate". Maybe "--borrow", but that does not
>> necessarily carry the implication that the relationship ends as soon as
>> the clone is done.
> 
> You are retracing the exact line of the thinking that led me to a
> cop-out that is a separate "--dissociate".
> 
> The original idea was to give "--borrow /local/repository/path", but
> that would have made it unclear what the differences between that
> new option and existing "--reference" were.  Both borrow the objects
> in order to reduce the network cost, and the difference is that one
> keeps borrowing while the other one limits the borrowing to strictly
> the initial phase.  The two words, "borrow" and "reference", would
> not convey that key distinction.  "Do the reference thing (which is
> well understood from old days, even before v1.6.0) and then severe
> the ties" was suboptimal but was easy to explain, and that is why I
> call it a cop-out.
> 
>> What is really happening is that we are reusing
>> objects in order to save bandwidth. Maybe "--reuse-from" would work?
>>
>> I dunno. I am not extremely happy with any of the suggestions I made,...
> 
> I dunno, either.
> 
> We are all on the same page.  We know the cop-out is suboptimal, we
> understand why the cop-out is better than "--borrow", and we cannot
> come up with a better name that contrasts with the existing
> "--reference" to make it clear how the new thing is different.

I'll take that as an invitation to brainstorm :-)

    --use-objects-from=
    --copy-objects-from=
    --precopy-objects-from=
    --precopy-from=
    --donor=
    --object-donor=
    --steal-from=
    --steal-objects-from=

Of these, I think I like "--object-donor" the best.

By the way, once we have stopped thinking about this feature as
"--reference" and then "--dissociate", it becomes obvious that a nice
generalization would be to allow *any* repository (including remote
ones) to serve as the object donor. This would allow users to get most
of their objects from a "nearby" repository (e.g., a mirror on the LAN)
and then top off from a more distant "authoritative" repository.

In fact, this donor/recipient relationship could be made persistent:
before fetching from repository A, always first fetch any objects that
repository B has available. OTOH, making the relationship persistent
would presumably require us to retain remote-tracking references for
repository B even though they are not intrinsically interesting to the
user, and would lead to reference namespace conflicts if the user wants
a "--mirror" clone.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu

Re: [PATCH 1/2] clone: add disassociate alias to dissociate option

[Junio C Hamano]

Michael Haggerty <mhagger@alum.mit.edu> writes:

> On 02/22/2015 07:32 PM, Junio C Hamano wrote:
>> ...  Both borrow the objects
>> in order to reduce the network cost, and the difference is that one
>> keeps borrowing while the other one limits the borrowing to strictly
>> the initial phase.  The two words, "borrow" and "reference", would
>> not convey that key distinction. ... and that is why I
>> call it a cop-out.
>> ...
>> We are all on the same page.  We know the cop-out is suboptimal, we
>> understand why the cop-out is better than "--borrow", and we cannot
>> come up with a better name that contrasts with the existing
>> "--reference" to make it clear how the new thing is different.
>
> I'll take that as an invitation to brainstorm :-)
>
>     --use-objects-from=
>     --copy-objects-from=
>     --precopy-objects-from=
>     --precopy-from=
>     --donor=
>     --object-donor=
>     --steal-from=
>     --steal-objects-from=
>
> Of these, I think I like "--object-donor" the best.

Donor (somehow the word reminds me of organ harvesting, yuck)?

I didn't think of the word 'copy', but that probably captures the
essence the best.  "reference-to-borrow-and-then-dissociate" is an
implementation detail, which, as you say, we do not want the users
to view this operation as; copying locally instead of over the
network is what the user wants to do.

> By the way, once we have stopped thinking about this feature as
> "--reference" and then "--dissociate", it becomes obvious that a nice
> generalization would be to allow *any* repository (including remote
> ones) to serve as the object donor.

As I do not think of a workable approach to implement such a
mechanism, I'd refrain from being irresponsible and say "Yeah,
that's a neat idea", which would make me sound like clueless "me
too, why doesn't Git do that?" crowd.

Re: [PATCH 1/2] clone: add disassociate alias to dissociate option

[Michael Haggerty]

On 02/24/2015 09:06 PM, Junio C Hamano wrote:
> Michael Haggerty <mhagger@alum.mit.edu> writes:
>> By the way, once we have stopped thinking about this feature as
>> "--reference" and then "--dissociate", it becomes obvious that a nice
>> generalization would be to allow *any* repository (including remote
>> ones) to serve as the object donor.
> 
> As I do not think of a workable approach to implement such a
> mechanism, I'd refrain from being irresponsible and say "Yeah,
> that's a neat idea", which would make me sound like clueless "me
> too, why doesn't Git do that?" crowd.

I think this would be done by effectively creating a clone of the nearby
repository then a fetch of the distant one, with some reference
shuffling between the steps. If the nearby repository contains far more
objects than the user really wants, then the initial clone will be
wasteful. But since the use case will probably be that the nearby
repository is (1) a mirror of the distant repo, and (depending on how
old it is) contains approximately a subset of the objects in the distant
repository, and (2) much faster to work with than the distant repo, I
think even this crude approach would often be a win.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu