threads / rfc / 33870

RFC patch, 2 partsconfig doc: add dot-repository note

Subject: [RFC/PATCH 1/2] config doc: add dot-repository note

## tl;dr

33 messages between May 19, 2013 and Sep 14, 2013. Diffs are folded; open one to read it.

replies: 32people: 4as markdown or json

Philip Oakley· May 19, 2013, 11:54 UTC · lore

[RFC/PATCH 0/2] Extend dot repository documentation

The dot repository convention is not well know to users and its documenation is hidden as a note in an ancilliary config variable's documenation.

Document the dot repository 'do what I mean' convention in the config variable it is used in, and in the cli (command line interface) documenation page to give regular users a chance to find it.

Philip Oakley (2):
  config doc: add dot-repository note
  doc: command line interface (cli) dot-repository dwimmery
 Documentation/config.txt | 2 ++
 Documentation/gitcli.txt | 4 ++++
 2 files changed, 6 insertions(+)
-- 
1.8.1.msysgit.1
Philip Oakley· May 19, 2013, 11:54 UTC · re: Philip Oakley · lore

branch.<name>.remote can be set to '.' (period) as a dot repository as part of the remote name dwimmery. Tell the reader.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/config.txt | 2 ++
 1 file changed, 2 insertions(+)
Show changes to Documentation/config.txt +2 −0
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 6e53fc5..fd42509 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -734,6 +734,8 @@ branch.<name>.remote::
 	overridden by `branch.<name>.pushremote`.  If no remote is
 	configured, or if you are not on any branch, it defaults to
 	`origin` for fetching and `remote.pushdefault` for pushing.
+	Additionally, a `.` (period) means the current local repository
+	(a dot-repository), see `branch.<name>.merge`'s final note below.
 
 branch.<name>.pushremote::
 	When on branch <name>, it overrides `branch.<name>.remote` for

-- 
1.8.1.msysgit.1
Jonathan Nieder· May 19, 2013, 17:43 UTC · re: Philip Oakley · lore

Re: [RFC/PATCH 1/2] config doc: add dot-repository note

Philip Oakley wrote:
Show 8 quoted lines
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -734,6 +734,8 @@ branch.<name>.remote::
>  	overridden by `branch.<name>.pushremote`.  If no remote is
>  	configured, or if you are not on any branch, it defaults to
>  	`origin` for fetching and `remote.pushdefault` for pushing.
> +	Additionally, a `.` (period) means the current local repository
> +	(a dot-repository), see `branch.<name>.merge`'s final note below.
Does this accept an arbitrary git URL, or only remote names?

The current documentation makes it sound like the latter, which makes this exception seem very weird. Is it actually the former?

I think a cross-reference to the "git urls" or "git remotes" documentation would be a better way to go, instead of having to repeat the rules of URL syntax everywhere they are used.

Thanks, Jonathan

Junio C Hamano· May 20, 2013, 17:50 UTC · re: Jonathan Nieder · lore

Re: [RFC/PATCH 1/2] config doc: add dot-repository note

Jonathan Nieder <jrnieder@gmail.com> writes:
Show 12 quoted lines
> Philip Oakley wrote:
>
>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -734,6 +734,8 @@ branch.<name>.remote::
>>  	overridden by `branch.<name>.pushremote`.  If no remote is
>>  	configured, or if you are not on any branch, it defaults to
>>  	`origin` for fetching and `remote.pushdefault` for pushing.
>> +	Additionally, a `.` (period) means the current local repository
>> +	(a dot-repository), see `branch.<name>.merge`'s final note below.
>
> Does this accept an arbitrary git URL, or only remote names?

The branch.<name>.remote variable refers to remote names, and '.' often appears as a special name to refer to the local repository.

I think you can define it as URL and your "git fetch" (no args) will do the right thing in that it would:

 (1) fetch the history leading to the tip branch.<name>.merge branch
     from there; and
 (2) leave the result in FETCH_HEAD, so that "git merge FETCH_HEAD"
     can conclude the "git pull" you split into two manually by
     running "git fetch" first,

but I do not think there is a "while we create this branch" side effect UI like "--set-upstream-to" for doing so, except for setting it to '.' when you set upstream to a branch in the local repository. I.e.

	git checkout -t -b mywork master
        git branch --set-upstream-to master mywork

Also I think setting it to arbitrary URL would mean that you would not see any remote tracking ref (they are to be defined as a property of named remote with remote.<name>.fetch refspecs), so it is unclear how @{u} would work. @{u} works when the variable is set to '.', though.

For the above reasons, describing '.' as a special value for the variable that the end users are likely to see is a reasonable "white lie" for this part of the documentation.

Philip Oakley· May 20, 2013, 21:10 UTC · re: Junio C Hamano · lore

Re: [RFC/PATCH 1/2] config doc: add dot-repository note

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Monday, May 20, 2013 6:50 PM
Show 17 quoted lines
> Jonathan Nieder <jrnieder@gmail.com> writes:
>
>> Philip Oakley wrote:
>>
>>> --- a/Documentation/config.txt
>>> +++ b/Documentation/config.txt
>>> @@ -734,6 +734,8 @@ branch.<name>.remote::
>>>  overridden by `branch.<name>.pushremote`.  If no remote is
>>>  configured, or if you are not on any branch, it defaults to
>>>  `origin` for fetching and `remote.pushdefault` for pushing.
>>> + Additionally, a `.` (period) means the current local repository
>>> + (a dot-repository), see `branch.<name>.merge`'s final note below.
>>
>> Does this accept an arbitrary git URL, or only remote names?
>
> The branch.<name>.remote variable refers to remote names, and '.'
> often appears as a special name to refer to the local repository.

Initially I thought that the '.' wasn't going to be acceptable as a URL, and that the '.' would only apply to the defined <name> of the remote within the branch section.

Show 29 quoted lines
>
> I think you can define it as URL and your "git fetch" (no args) will
> do the right thing in that it would:
>
> (1) fetch the history leading to the tip branch.<name>.merge branch
>     from there; and
>
> (2) leave the result in FETCH_HEAD, so that "git merge FETCH_HEAD"
>     can conclude the "git pull" you split into two manually by
>     running "git fetch" first,
>
> but I do not think there is a "while we create this branch" side
> effect UI like "--set-upstream-to" for doing so, except for setting
> it to '.' when you set upstream to a branch in the local repository.
> I.e.
>
> git checkout -t -b mywork master
>        git branch --set-upstream-to master mywork
>
> Also I think setting it to arbitrary URL would mean that you would
> not see any remote tracking ref (they are to be defined as a
> property of named remote with remote.<name>.fetch refspecs), so it
> is unclear how @{u} would work.  @{u} works when the variable is set
> to '.', though.
>
> For the above reasons, describing '.' as a special value for the
> variable that the end users are likely to see is a reasonable "white
> lie" for this part of the documentation.
>
OK.
Philip Oakley· May 19, 2013, 11:54 UTC · re: Philip Oakley · lore

[RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

The Git cli will generally accept dot '.' (period) as equivalent to the current repository when appropriate. Tell the reader of this 'do what I mean' (dwim)mery action.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitcli.txt | 4 ++++
 1 file changed, 4 insertions(+)
Show changes to Documentation/gitcli.txt +4 −0
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 9ac5088..64bb386 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -59,6 +59,10 @@ working tree.  After running `git add hello.c; rm hello.c`, you will _not_
 see `hello.c` in your working tree with the former, but with the latter
 you will.
 
+Just as, by convention, the filesystem '.' refers to the current directory,
+using a '.' (period) as a repository name in Git (a dot-repository) refers
+to your local repository.
+
 Here are the rules regarding the "flags" that you should follow when you are
 scripting Git:
 

-- 
1.8.1.msysgit.1
Jonathan Nieder· May 19, 2013, 17:39 UTC · re: Philip Oakley · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

Hi,
Philip Oakley wrote:
> The Git cli will generally accept dot '.' (period) as equivalent
> to the current repository when appropriate. Tell the reader of this
> 'do what I mean' (dwim)mery action.
[...]
Show 9 quoted lines
> --- a/Documentation/gitcli.txt
> +++ b/Documentation/gitcli.txt
> @@ -59,6 +59,10 @@ working tree.  After running `git add hello.c; rm hello.c`, you will _not_
>  see `hello.c` in your working tree with the former, but with the latter
>  you will.
>  
> +Just as, by convention, the filesystem '.' refers to the current directory,
> +using a '.' (period) as a repository name in Git (a dot-repository) refers
> +to your local repository.
Good idea, but I fear that no one would find it there.

Would it make sense to put this in Documentation/urls.txt (aka the "GIT URLS" section of git-fetch(1) and git-clone(1)), where other URL schemes are documented?

Thanks, Jonathan

Philip Oakley· May 19, 2013, 22:29 UTC · re: Jonathan Nieder · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

From: "Jonathan Nieder" <jrnieder@gmail.com>
Sent: Sunday, May 19, 2013 6:39 PM
Show 30 quoted lines
> Hi,
>
> Philip Oakley wrote:
>
>> The Git cli will generally accept dot '.' (period) as equivalent
>> to the current repository when appropriate. Tell the reader of this
>> 'do what I mean' (dwim)mery action.
> [...]
>> --- a/Documentation/gitcli.txt
>> +++ b/Documentation/gitcli.txt
>> @@ -59,6 +59,10 @@ working tree.  After running `git add hello.c; rm 
>> hello.c`, you will _not_
>>  see `hello.c` in your working tree with the former, but with the 
>> latter
>>  you will.
>>
>> +Just as, by convention, the filesystem '.' refers to the current 
>> directory,
>> +using a '.' (period) as a repository name in Git (a dot-repository) 
>> refers
>> +to your local repository.
>
> Good idea, but I fear that no one would find it there.
>
> Would it make sense to put this in Documentation/urls.txt (aka the
> "GIT URLS" section of git-fetch(1) and git-clone(1)), where other URL
> schemes are documented?
>
> Thanks,
> Jonathan

Sounds an interesting idea. I'll have a look. Philip

Junio C Hamano· May 20, 2013, 17:55 UTC · re: Jonathan Nieder · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

Jonathan Nieder <jrnieder@gmail.com> writes:
Show 11 quoted lines
>> --- a/Documentation/gitcli.txt
>> +++ b/Documentation/gitcli.txt
>> @@ -59,6 +59,10 @@ working tree.  After running `git add hello.c; rm hello.c`, you will _not_
>>  see `hello.c` in your working tree with the former, but with the latter
>>  you will.
>>  
>> +Just as, by convention, the filesystem '.' refers to the current directory,
>> +using a '.' (period) as a repository name in Git (a dot-repository) refers
>> +to your local repository.
>
> Good idea, but I fear that no one would find it there.

Also I think it would be better without ", by convention,". If you say '.' == current directory is "a convention", you have to start saying that "by convention", "hello.c" refers to the file in the current directory of that name, which may be technically correct but make the phrase "by convention" meaningless. A dot "." is *the* name for the current directory, just like "hello.c" is the name for that file.

    Just like '.' refers to the current directory in the filesystem, '.'
    refers to the current repository.
would be sufficient.
> Would it make sense to put this in Documentation/urls.txt (aka the
> "GIT URLS" section of git-fetch(1) and git-clone(1)), where other URL
> schemes are documented?

Yes, the '.' described above is a special case of giving a repository URL as a relative-path on the filesystem.

Philip Oakley· May 20, 2013, 21:09 UTC · re: Junio C Hamano · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Monday, May 20, 2013 6:55 PM
Show 25 quoted lines
> Jonathan Nieder <jrnieder@gmail.com> writes:
>
>>> --- a/Documentation/gitcli.txt
>>> +++ b/Documentation/gitcli.txt
>>> @@ -59,6 +59,10 @@ working tree.  After running `git add hello.c; rm 
>>> hello.c`, you will _not_
>>>  see `hello.c` in your working tree with the former, but with the 
>>> latter
>>>  you will.
>>>
>>> +Just as, by convention, the filesystem '.' refers to the current 
>>> directory,
>>> +using a '.' (period) as a repository name in Git (a dot-repository) 
>>> refers
>>> +to your local repository.
>>
>> Good idea, but I fear that no one would find it there.
>
> Also I think it would be better without ", by convention,".  If you
> say '.' == current directory is "a convention", you have to start
> saying that "by convention", "hello.c" refers to the file in the
> current directory of that name, which may be technically correct but
> make the phrase "by convention" meaningless.  A dot "."  is *the*
> name for the current directory, just like "hello.c" is the name for
> that file.

The part I had previously needed clearing up was if the '.' was in some way expanded by the shell, or whether the file system commands interpreted it by themselves for that specific purpose. So in this case Git sees the single character and has to decide what to do with it.

Show 13 quoted lines
>
>    Just like '.' refers to the current directory in the filesystem, 
> '.'
>    refers to the current repository.
>
> would be sufficient.
>
>> Would it make sense to put this in Documentation/urls.txt (aka the
>> "GIT URLS" section of git-fetch(1) and git-clone(1)), where other URL
>> schemes are documented?
>
> Yes, the '.' described above is a special case of giving a
> repository URL as a relative-path on the filesystem.

So we can have a branch whose remote is '.' _and_ a remote whose URL is '.'

Hence we/one/I could declare a remote called 'home' whose URL is '.' (with my 'away' remote on Github - just thinking aloud of the upstream / downstream / across-stream discussions!)

Can there be a clash with a named remote that is actually '.', where the push/fetch is actually a no-op?

Philip
Junio C Hamano· May 20, 2013, 22:22 UTC · re: Philip Oakley · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

"Philip Oakley" <philipoakley@iee.org> writes:
> So we can have a branch whose remote is '.'
> _and_ a remote whose URL is '.'
Yes, and they are two separate concepts.
"git fetch" while on "mywork" branch with this:
    [branch "mywork"]
        remote = git://git.k.org/pub/scm/git/git.git
        merge = refs/heads/master

without having any named remote whose remote.$name.url is set to that URL may happen to work but it is by accident as far as I know. As you do not copy to any remote tracking branches, @{u} would not work, so it is not something useful. But on the other hand

    [branch "mywork"]
        remote = .
        merge = refs/heads/master
works _as if_ you have
    [remote "."]
        url = "."
	;; no fetch refspec like +refs/heads/*:refs/heads/*
        ;; no push refspec like +refs/heads/*:refs/heads/*

so in that sense, you _could_ think of branch.$name.remote as a (generic) URL or a name of a (special) remote, but it is easier to think about it as the latter.

And remote.$name.url = "." for any name, e.g.
    [remote "here"]
        url = "."

is a special case of local repository that is named with a relative filesystem path.

> Can there be a clash with a named remote that is actually '.', where
> the push/fetch is actually a no-op?
Nobody sane would do it in the first place, so...
Philip Oakley· May 21, 2013, 07:47 UTC · re: Junio C Hamano · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Monday, May 20, 2013 11:22 PM
Show 6 quoted lines
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> So we can have a branch whose remote is '.'
>> _and_ a remote whose URL is '.'
>
> Yes, and they are two separate concepts.
Thank you of the confirmation.
Show 9 quoted lines
>
> "git fetch" while on "mywork" branch with this:
>
>    [branch "mywork"]
>        remote = git://git.k.org/pub/scm/git/git.git
>        merge = refs/heads/master
>
> without having any named remote whose remote.$name.url is set to
> that URL may happen to work but it is by accident as far as I know.

Interesting. Any thoughts on which way it should be documented/deprecated?

Show 8 quoted lines
> As you do not copy to any remote tracking branches, @{u} would not
> work, so it is not something useful.  But on the other hand
>
>    [branch "mywork"]
>        remote = .
>        merge = refs/heads/master
>
> works _as if_ you have
Thank you of the confirmation.
Show 9 quoted lines
>
>    [remote "."]
>        url = "."
> ;; no fetch refspec like +refs/heads/*:refs/heads/*
>        ;; no push refspec like +refs/heads/*:refs/heads/*
>
> so in that sense, you _could_ think of branch.$name.remote as a
> (generic) URL or a name of a (special) remote, but it is easier to
> think about it as the latter.
Yes.
Show 13 quoted lines
>
> And remote.$name.url = "." for any name, e.g.
>
>    [remote "here"]
>        url = "."
>
> is a special case of local repository that is named with a relative
> filesystem path.
>
>> Can there be a clash with a named remote that is actually '.', where
>> the push/fetch is actually a no-op?
>
> Nobody sane would do it in the first place, so...

Oh I don't know. I don't think 'sanity' comes into it any more than 'common sense' is common. It's easy to fall into the inverse Kruger-Dunning mode where those in the know don't realise how much they know, and how 'stupid' those that don't can be (that'd be me;-).

All this 'what's a dot-repo and where can I use it' came about because of an answer that give it's use as a 'trick'.

On Sat, May 4, 2013 at 2:51 PM, Jonathan Nieder <jrnieder@gmail.com> wrote:

> Another trick is to use "git push":
>         git push . $production_sha1:refs/heads/master
and

Filipe gave 'git fetch .' in [PATCH 1/3] fetch: add --allow-local option, 16 May 2013

Philip
Junio C Hamano· May 21, 2013, 16:23 UTC · re: Philip Oakley · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

"Philip Oakley" <philipoakley@iee.org> writes:
Show 21 quoted lines
> From: "Junio C Hamano" <gitster@pobox.com>
> Sent: Monday, May 20, 2013 11:22 PM
>> "Philip Oakley" <philipoakley@iee.org> writes:
>>
>>> So we can have a branch whose remote is '.'
>>> _and_ a remote whose URL is '.'
>>
>> Yes, and they are two separate concepts.
> Thank you of the confirmation.
>
>>
>> "git fetch" while on "mywork" branch with this:
>>
>>    [branch "mywork"]
>>        remote = git://git.k.org/pub/scm/git/git.git
>>        merge = refs/heads/master
>>
>> without having any named remote whose remote.$name.url is set to
>> that URL may happen to work but it is by accident as far as I know.
> Interesting. Any thoughts on which way it should be
> documented/deprecated?

If "leave it as-is" is not an option, I personally would prefer mentioning "this happens to work, but do not rely on it" in the passing. I do not see any immediate need to break things for people discovered that this happens to work and who decided that they have no need for a remote tracking branch for the particular remote this branch happens to integrate with. By making that choice, they may be forgoing the use of @{u}, but they won't be inconvenienced as "git fetch" will leave what they need @{u} for in FETCH_HEAD, i.e. instead of doing

	git fetch
	git log [-p] ..@{u}
        git merge @{u} ;# or git rebase @{u}

as a "verify in the middle" replacement for "git pull [--rebase]", they can do

	git fetch
	git log [-p] ..FETCH_HEAD
        git merge FETCH_HEAD ;# or git rebase FETCH_HEAD
just fine.

The "do not rely on it" is primarily because there are more familiar ways invented later (namely, use a named remote instead of writing a real URL, with remote tracking branches). I do not think we would want to deliberately sabotage the people who currently use such a setting, but I do not see a strong reason to recommend it to people who are new to Git, either, *unless* they need to fetch from many different places and do not want to have remote tracking branches because the only time they care about the state of their remotes is immediately after they fetched.

Show 9 quoted lines
>>> Can there be a clash with a named remote that is actually '.', where
>>> the push/fetch is actually a no-op?
>>
>> Nobody sane would do it in the first place, so...
>
> Oh I don't know. I don't think 'sanity' comes into it any more than
> common sense' is common. It's easy to fall into the inverse
> Kruger-Dunning mode where those in the know don't realise how much
> they know, and how 'stupid' those that don't can be (that'd be me;-).

How would you even express such a remote named "." in the first place? "git remote add" would not let you say:

	$ git remote add . git://some.where.xz/some/repo.git
        fatal: '.' is not a valid remote name

and even if you add configuration variables by hand, it would not look like this:

	[remote "."]
        	fetch = +refs/heads/*:refs/remotes/./*

You would want some real token between "refs/remotes/" and the trailing "/*" instead, so...

Show 7 quoted lines
> All this 'what's a dot-repo and where can I use it' came about because
> of an answer that give it's use as a 'trick'.
>
> On Sat, May 4, 2013 at 2:51 PM, Jonathan Nieder <jrnieder@gmail.com>
> wrote:
>> Another trick is to use "git push":
>>         git push . $production_sha1:refs/heads/master

It all falls out naturally from the "Git is distributed and no repository is special" principle. I think that word "trick" merely refers to "those who do not realize that the local repository is not all that special and merely is _a_ repository just like anybody else's may not realize they can do this", nothing more.

> Filipe gave 'git fetch .' in [PATCH 1/3] fetch: add --allow-local
> option, 16 May 2013

That patch came from a mistaken suggestion from me that was retracted with

    http://article.gmane.org/gmane.comp.version-control.git/224729
Felipe Contreras· May 21, 2013, 21:21 UTC · re: Junio C Hamano · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

On Tue, May 21, 2013 at 11:23 AM, Junio C Hamano <gitster@pobox.com> wrote:
> "Philip Oakley" <philipoakley@iee.org> writes:
Show 10 quoted lines
>> On Sat, May 4, 2013 at 2:51 PM, Jonathan Nieder <jrnieder@gmail.com>
>> wrote:
>>> Another trick is to use "git push":
>>>         git push . $production_sha1:refs/heads/master
>
> It all falls out naturally from the "Git is distributed and no
> repository is special" principle.  I think that word "trick" merely
> refers to "those who do not realize that the local repository is not
> all that special and merely is _a_ repository just like anybody
> else's may not realize they can do this", nothing more.
Nobody cares.
Show 5 quoted lines
>> Filipe gave 'git fetch .' in [PATCH 1/3] fetch: add --allow-local
>> option, 16 May 2013
>
> That patch came from a mistaken suggestion from me that was
> retracted with

You say it's "mistaken", but you are not the arbiter of truth; the fact that you say it's so doesn't make it so. It's just rhetoric.

You haven't shown that it's indeed mistaken.
-- 
Felipe Contreras
Philip Oakley· May 21, 2013, 22:33 UTC · re: Felipe Contreras · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

From: "Felipe Contreras" <felipe.contreras@gmail.com>
Sent: Tuesday, May 21, 2013 10:21 PM
Show 16 quoted lines
> On Tue, May 21, 2013 at 11:23 AM, Junio C Hamano <gitster@pobox.com> 
> wrote:
>> "Philip Oakley" <philipoakley@iee.org> writes:
>
>>> On Sat, May 4, 2013 at 2:51 PM, Jonathan Nieder <jrnieder@gmail.com>
>>> wrote:
>>>> Another trick is to use "git push":
>>>>         git push . $production_sha1:refs/heads/master
>>
>> It all falls out naturally from the "Git is distributed and no
>> repository is special" principle.  I think that word "trick" merely
>> refers to "those who do not realize that the local repository is not
>> all that special and merely is _a_ repository just like anybody
>> else's may not realize they can do this", nothing more.
>
> Nobody cares.

The value of the trick was acknowledged as now being in use http://article.gmane.org/gmane.comp.version-control.git/223572 Not sure if that was the caring you were commenting on.

My patch was to make it better known and that it (the dot repository) isn't a 'trick'.

I'll refresh them after v1.8.3.
Show 11 quoted lines
>
>>> Filipe gave 'git fetch .' in [PATCH 1/3] fetch: add --allow-local
>>> option, 16 May 2013
>>
>> That patch came from a mistaken suggestion from me that was
>> retracted with
>
> You say it's "mistaken", but you are not the arbiter of truth; the
> fact that you say it's so doesn't make it so. It's just rhetoric.
>
> You haven't shown that it's indeed mistaken.

An aside: in some domains (e.g. Human Error taxonomy) a 'mistake' is a planned action which later turns out to not be the action that would now have, in retrospect, been chosen. The intent was good, but is later classed (within the taxonomy) as a 'mistake'. (It is not related to 'blame').

If I understand the extended thread correctly, the approach moved on and alternatives were found, so in that sense the intent was good.

>
> -- 
> Felipe Contreras
Felipe Contreras· May 21, 2013, 23:03 UTC · re: Philip Oakley · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

On Tue, May 21, 2013 at 5:33 PM, Philip Oakley <philipoakley@iee.org> wrote:
Show 26 quoted lines
> From: "Felipe Contreras" <felipe.contreras@gmail.com>
> Sent: Tuesday, May 21, 2013 10:21 PM
>
>> On Tue, May 21, 2013 at 11:23 AM, Junio C Hamano <gitster@pobox.com>
>> wrote:
>>>
>>> "Philip Oakley" <philipoakley@iee.org> writes:
>>
>>
>>>> On Sat, May 4, 2013 at 2:51 PM, Jonathan Nieder <jrnieder@gmail.com>
>>>> wrote:
>>>>>
>>>>> Another trick is to use "git push":
>>>>>         git push . $production_sha1:refs/heads/master
>>>
>>>
>>> It all falls out naturally from the "Git is distributed and no
>>> repository is special" principle.  I think that word "trick" merely
>>> refers to "those who do not realize that the local repository is not
>>> all that special and merely is _a_ repository just like anybody
>>> else's may not realize they can do this", nothing more.
>>
>> Nobody cares.
>
> The value of the trick was acknowledged as now being in use
> http://article.gmane.org/gmane.comp.version-control.git/223572
How is that more useful than 'git branch -f master $sha1'?
> Not sure if that was the caring you were commenting on.

My point is that nobody uses '.' as a remote. Yes, you can find the occasional esoteric person in the Git mailing list that might find some weird command useful, but that's the fringe user-base.

Show 10 quoted lines
>> You say it's "mistaken", but you are not the arbiter of truth; the
>> fact that you say it's so doesn't make it so. It's just rhetoric.
>>
>> You haven't shown that it's indeed mistaken.
>
>
> An aside: in some domains (e.g. Human Error taxonomy) a 'mistake' is a
> planned action which later turns out to not be the action that would now
> have, in retrospect, been chosen. The intent was good, but is later classed
> (within the taxonomy) as a 'mistake'. (It is not related to 'blame').
Yeah, that's what a mistake is, in my mind.
> If I understand the extended thread correctly, the approach moved on and
> alternatives were found, so in that sense the intent was good.

No, the approach didn't move on, there are no better alternatives, the "intent" is irrelevant, the approach is good, there is no mistake.

Junio simply ignored the fact that he was proven wrong.
I still haven't received a response: which makes more sense?
a)
	% git checkout svn-ext
	% git fetch
	From .
	 * branch            master     -> FETCH_HEAD
	# oops
	% git fetch git-svn
	% git log ..FETCH_HEAD
	% git merge FETCH_HEAD
b)
	% git checkout svn-ext
	% git fetch
	From git://git.kernel.org/pub/scm/git/git
	   680ed3e..de3a5c6  master     -> origin/master
	# oops
	% git fetch svn-ext
	% git log ..FETCH_HEAD
	% git merge FETCH_HEAD
-- 
Felipe Contreras
Junio C Hamano· May 21, 2013, 23:24 UTC · re: Felipe Contreras · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

Felipe Contreras <felipe.contreras@gmail.com> writes:
Show 23 quoted lines
> I still haven't received a response: which makes more sense?
>
> a)
>
> 	% git checkout svn-ext
> 	% git fetch
> 	From .
> 	 * branch            master     -> FETCH_HEAD
> 	# oops
> 	% git fetch git-svn
> 	% git log ..FETCH_HEAD
> 	% git merge FETCH_HEAD
>
> b)
>
> 	% git checkout svn-ext
> 	% git fetch
> 	From git://git.kernel.org/pub/scm/git/git
> 	   680ed3e..de3a5c6  master     -> origin/master
> 	# oops
> 	% git fetch svn-ext
> 	% git log ..FETCH_HEAD
> 	% git merge FETCH_HEAD

I think with the scenario you are following, a) would prepare the FETCH_HEAD with her local git-svn branch which is her svn-ext topic is based on, but you illustrated it to fetch 'master', which I think is a minor typo.

Modulo that typo, the step before the #oops makes perfect sense. It fetched where she told Git her work on svn-ext is based on.

But the step after that does not make much sense in that flow.

"git fetch git-svn" to get from Eric might make sense but running log with FETCH_HEAD while she is on her svn-ext does not make any sense, let alone merging with it. Her svn-ext is based on her local git-svn branch for a reason---her branches are cascaded this way:

    Eric --> her local git-svn --> her local svn-ext

Hecking out her git-svn to update/rebase it on top of Eric's latest and then update her svn-ext that is based on her git-svn may make sense. But fetching from Eric and merging it into her svn-ext directly does not.

And what happens before #oops in b) is an utter nonsense. Her svn-ext is not even related to my tree. I think the step after that is a typo of "git fetch git-svn" to fetch from Eric, but again, because svn-ext is fork from her local git-svn (which is ahead of Eric's tree with her own changes, but the changes are not related to her svn-ext work), these "fetch from Eric, integrate svn-ext directly with it" makes no sense.

So, the short answer is neither, but a) can be fixed (not in code but in the typescript) to make more sense, perhaps like this:

    % git checkout svn-ext
    % git fetch
    % git log ..FETCH_HEAD
    % git rebase FETCH_HEAD
    # The last three can be "git pull --rebase".
    # ok, did Eric do something in the meantime?
    % git checkout git-svn
    % git fetch
    From git://git.bogomips.org/git-svn.git/
     * branch  master -> git-svn/master
    % git rebase FETCH_HEAD
    # now let's rebuild the svn-ext on top
    % git checkout svn-ext
    % git pull --rebase

The last step can be "git rebase git-svn", and the step to update git-svn from Eric after checking it out can be "git pull --rebase", but the whole point of having @{u}, even for branches that fork from a local branch, is so that the user does not have to remember what forks from what, so I did not force her to say "git rebase git-svn" in that step.

Felipe Contreras· May 22, 2013, 00:27 UTC · re: Junio C Hamano · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

On Tue, May 21, 2013 at 6:24 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 35 quoted lines
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> I still haven't received a response: which makes more sense?
>>
>> a)
>>
>>       % git checkout svn-ext
>>       % git fetch
>>       From .
>>        * branch            master     -> FETCH_HEAD
>>       # oops
>>       % git fetch git-svn
>>       % git log ..FETCH_HEAD
>>       % git merge FETCH_HEAD
>>
>> b)
>>
>>       % git checkout svn-ext
>>       % git fetch
>>       From git://git.kernel.org/pub/scm/git/git
>>          680ed3e..de3a5c6  master     -> origin/master
>>       # oops
>>       % git fetch svn-ext
>>       % git log ..FETCH_HEAD
>>       % git merge FETCH_HEAD
>
> I think with the scenario you are following, a) would prepare the
> FETCH_HEAD with her local git-svn branch which is her svn-ext topic
> is based on, but you illustrated it to fetch 'master', which I think
> is a minor typo.
>
> Modulo that typo, the step before the #oops makes perfect sense.  It
> fetched where she told Git her work on svn-ext is based on.
>
> But the step after that does not make much sense in that flow.

You don't get to decide what Sally (I'm naming her) does, all you get to decide is what Git does.

Sally wants to fetch from the true upstream: svn-ext, but in the process does by mistake a 'git fetch' *without arguments* (WHICH IS WHAT THIS WHOLE DISCUSSION IS ABOUT). So now is the time you answer: a) or b).

You whole argument resides on this question, because you assumed the answer is a), but that's an *assumption*, answer the question and you'll see why. But your solution to a question that would undermine your argument is to just ditch it. Great.

> So, the short answer is neither, but a) can be fixed (not in code
> but in the typescript) to make more sense, perhaps like this:
Do not avoid the question.
Show 5 quoted lines
>     % git checkout svn-ext
>     % git fetch
>     % git log ..FETCH_HEAD
>     % git rebase FETCH_HEAD
>     # The last three can be "git pull --rebase".

If she does 'git pull --rebase', then the whole thing is irrelevant for the disunion about GIT FETCH WITHOUT ARGUMENTS.

She didn't want to fetch '.', nobody does; she wanted to fetch a real remote repository.

Show 6 quoted lines
>     # ok, did Eric do something in the meantime?
>     % git checkout git-svn
>     % git fetch
>     From git://git.bogomips.org/git-svn.git/
>      * branch  master -> git-svn/master
>     % git rebase FETCH_HEAD
This 'git fetch' is irrelevant, because it's not fetching from '.'.
>     # now let's rebuild the svn-ext on top
>     % git checkout svn-ext
>     % git pull --rebase
No fetch without arguments here either.
All these commands are red herrings.

Is it a) or b) or are you just going to never allow your argument to be challenged? That's a great way to "win" arguments, but a bad one to arrive to good solutions.

-- 
Felipe Contreras
Junio C Hamano· May 22, 2013, 00:50 UTC · re: Felipe Contreras · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

Felipe Contreras <felipe.contreras@gmail.com> writes:
Show 44 quoted lines
> On Tue, May 21, 2013 at 6:24 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>
>>> I still haven't received a response: which makes more sense?
>>>
>>> a)
>>>
>>>       % git checkout svn-ext
>>>       % git fetch
>>>       From .
>>>        * branch            master     -> FETCH_HEAD
>>>       # oops
>>>       % git fetch git-svn
>>>       % git log ..FETCH_HEAD
>>>       % git merge FETCH_HEAD
>>>
>>> b)
>>>
>>>       % git checkout svn-ext
>>>       % git fetch
>>>       From git://git.kernel.org/pub/scm/git/git
>>>          680ed3e..de3a5c6  master     -> origin/master
>>>       # oops
>>>       % git fetch svn-ext
>>>       % git log ..FETCH_HEAD
>>>       % git merge FETCH_HEAD
>>
>> I think with the scenario you are following, a) would prepare the
>> FETCH_HEAD with her local git-svn branch which is her svn-ext topic
>> is based on, but you illustrated it to fetch 'master', which I think
>> is a minor typo.
>>
>> Modulo that typo, the step before the #oops makes perfect sense.  It
>> fetched where she told Git her work on svn-ext is based on.
>>
>> But the step after that does not make much sense in that flow.
>
> You don't get to decide what Sally (I'm naming her) does, all you get
> to decide is what Git does.
>
> Sally wants to fetch from the true upstream: svn-ext, but in the
> process does by mistake a 'git fetch' *without arguments* (WHICH IS
> WHAT THIS WHOLE DISCUSSION IS ABOUT). So now is the time you answer:
> a) or b).
Heh, that was my example.

In any case, my pick is still a). She *TOLD* Git that her local git-svn branch is what forms the base of her local svn-ext work.

I won't even read the remainder. You are not even worth wasting time on discussing this.

Felipe Contreras· May 22, 2013, 02:57 UTC · re: Junio C Hamano · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

On Tue, May 21, 2013 at 7:50 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 51 quoted lines
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> On Tue, May 21, 2013 at 6:24 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>>
>>>> I still haven't received a response: which makes more sense?
>>>>
>>>> a)
>>>>
>>>>       % git checkout svn-ext
>>>>       % git fetch
>>>>       From .
>>>>        * branch            master     -> FETCH_HEAD
>>>>       # oops
>>>>       % git fetch git-svn
>>>>       % git log ..FETCH_HEAD
>>>>       % git merge FETCH_HEAD
>>>>
>>>> b)
>>>>
>>>>       % git checkout svn-ext
>>>>       % git fetch
>>>>       From git://git.kernel.org/pub/scm/git/git
>>>>          680ed3e..de3a5c6  master     -> origin/master
>>>>       # oops
>>>>       % git fetch svn-ext
>>>>       % git log ..FETCH_HEAD
>>>>       % git merge FETCH_HEAD
>>>
>>> I think with the scenario you are following, a) would prepare the
>>> FETCH_HEAD with her local git-svn branch which is her svn-ext topic
>>> is based on, but you illustrated it to fetch 'master', which I think
>>> is a minor typo.
>>>
>>> Modulo that typo, the step before the #oops makes perfect sense.  It
>>> fetched where she told Git her work on svn-ext is based on.
>>>
>>> But the step after that does not make much sense in that flow.
>>
>> You don't get to decide what Sally (I'm naming her) does, all you get
>> to decide is what Git does.
>>
>> Sally wants to fetch from the true upstream: svn-ext, but in the
>> process does by mistake a 'git fetch' *without arguments* (WHICH IS
>> WHAT THIS WHOLE DISCUSSION IS ABOUT). So now is the time you answer:
>> a) or b).
>
> Heh, that was my example.
>
> In any case, my pick is still a).  She *TOLD* Git that her local
> git-svn branch is what forms the base of her local svn-ext work.

She told Git that her local svn-branch was the basis for svn-next. She DIT NOT TELL Git to fetch from there. She told Git to fetch from any location Git thought best to fetch from, either a) or b) would fetch from the wrong location, but a) would be wronger, you just don't want to admit it.

You are, once again, *assuming* that if a user sets up an upstream, he wants to fetch from there. All you answers are based on assumptions.

-- 
Felipe Contreras
Junio C Hamano· May 22, 2013, 16:50 UTC · re: Felipe Contreras · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

Felipe Contreras <felipe.contreras@gmail.com> writes:
Show 5 quoted lines
> She told Git that her local svn-branch was the basis for svn-next. She
> DIT NOT TELL Git to fetch from there. She told Git to fetch from any
> location Git thought best to fetch from, either a) or b) would fetch
> from the wrong location, but a) would be wronger, you just don't want
> to admit it.
"(a) is more wrong" is just your opinion, and you are simply wrong.

She is working on svn-ext based on her local git-svn the latter of which has some changes of her own on top of Eric's tree.

When working on _any_ branch that bases its work on something else, you have @{u} available, but that @{u} will not stay up-to-date if you forked from work that is done outside your repository. That is what an unqualified "git fetch" is designed to help when run on a branch that bases its work on something else. If you happen to know that yoru current branch is forked from git-svn that is a local branch, then running "git fetch" becomes unnecessary for the purpose of updating @{u} (it already and always is up to date), so doing no object transfer and no ref update is absolutely the right thing to do. That is what "remote = ." gives you.

In addition, that does not break the "pull = fetch + merge" equivalence you seem to be ignoring.

If she wants to check what Eric has been doing, she can do "git fetch git-svn", giving the remote name she calls Eric's tree with. At that point, she is not saying "I want to check what is happening to the upstream of my _current_ branch" (and the fetched result is not something she can immediately use while on her current branch).

On the other hand, an unqualified "git fetch" that slurps from my tree, which is your (b), is just plain wrong. My tree is not even related to what she is working on.

Of course, when she is interested in what have been happening in my tree, she can say "git fetch origin".

Felipe Contreras· May 22, 2013, 22:12 UTC · re: Junio C Hamano · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

On Wed, May 22, 2013 at 11:50 AM, Junio C Hamano <gitster@pobox.com> wrote:
Show 9 quoted lines
> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> She told Git that her local svn-branch was the basis for svn-next. She
>> DIT NOT TELL Git to fetch from there. She told Git to fetch from any
>> location Git thought best to fetch from, either a) or b) would fetch
>> from the wrong location, but a) would be wronger, you just don't want
>> to admit it.
>
> "(a) is more wrong" is just your opinion, and you are simply wrong.

My opinion based on very solid grounds; the whole purpose of 'git fetch; is to FETCH from a REMOTE. a) is not doing that at all.

In addition, the vast majority of users don't have a clue as to what  the hell
>From .
        * branch            master     -> FETCH_HEAD
means.
a) is wronger. Period.
You say it's not, but give no explanation at all. This is no way to argue.
Show 8 quoted lines
> She is working on svn-ext based on her local git-svn the latter of
> which has some changes of her own on top of Eric's tree.
>
> When working on _any_ branch that bases its work on something else,
> you have @{u} available, but that @{u} will not stay up-to-date if
> you forked from work that is done outside your repository.  That is
> what an unqualified "git fetch" is designed to help when run on a
> branch that bases its work on something else.

The fact that it's designed that way doesn't mean it's a good design, and it doesn't mean the user expects that.

> If you happen to know
> that yoru current branch is forked from git-svn that is a local
> branch,
That's a very big *IF*.
> then running "git fetch" becomes unnecessary for the purpose
> of updating @{u} (it already and always is up to date), so doing no
> object transfer and no ref update is absolutely the right thing to
> do.  That is what "remote = ." gives you.
Jumping to conclusions based on assumptions again.

Sally doesn't know what the designers intended, Sally doesn't remember what is the upstream of the current branch, of it has any upstream at all. Sally does 'git fetch' instinctively, and expects Git to do the right thing, but it doesn't, it does an utterly irrelevant and useless action; non-fetching from a local-remote.

> In addition, that does not break the "pull = fetch + merge"
> equivalence you seem to be ignoring.

Do you want me to count to you the many times I've proved to you that pull is NOT fetch + merge?

YOU are the one ignoring the fact that it's not: it's only that way in very specific circumstances, certaily ver far from being a universal truth.

Show 5 quoted lines
> If she wants to check what Eric has been doing, she can do "git
> fetch git-svn", giving the remote name she calls Eric's tree with.
> At that point, she is not saying "I want to check what is happening
> to the upstream of my _current_ branch" (and the fetched result is
> not something she can immediately use while on her current branch).
Irrelevant.
> On the other hand, an unqualified "git fetch" that slurps from my
> tree, which is your (b), is just plain wrong.
But that's *EXACTLY* what we do when there's no upstream branch, is it not?
> My tree is not even
> related to what she is working on.

Unless you are prepared to say fetching from any other tree that @{u} is wrong, and 'git fetch' should forbit it, this is irrelevant.

The user can fetch from wherever they want.
> Of course, when she is interested in what have been happening in my
> tree, she can say "git fetch origin".
Irrelevant. We are not changing that behavior.
-- 
Felipe Contreras
Philip Oakley· May 22, 2013, 22:09 UTC · re: Felipe Contreras · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

From: "Felipe Contreras" <felipe.contreras@gmail.com>
Sent: Wednesday, May 22, 2013 12:03 AM
Show 32 quoted lines
> On Tue, May 21, 2013 at 5:33 PM, Philip Oakley <philipoakley@iee.org> 
> wrote:
>> From: "Felipe Contreras" <felipe.contreras@gmail.com>
>> Sent: Tuesday, May 21, 2013 10:21 PM
>>
>>> On Tue, May 21, 2013 at 11:23 AM, Junio C Hamano <gitster@pobox.com>
>>> wrote:
>>>>
>>>> "Philip Oakley" <philipoakley@iee.org> writes:
>>>
>>>
>>>>> On Sat, May 4, 2013 at 2:51 PM, Jonathan Nieder 
>>>>> <jrnieder@gmail.com>
>>>>> wrote:
>>>>>>
>>>>>> Another trick is to use "git push":
>>>>>>         git push . $production_sha1:refs/heads/master
>>>>
>>>>
>>>> It all falls out naturally from the "Git is distributed and no
>>>> repository is special" principle.  I think that word "trick" merely
>>>> refers to "those who do not realize that the local repository is 
>>>> not
>>>> all that special and merely is _a_ repository just like anybody
>>>> else's may not realize they can do this", nothing more.
>>>
>>> Nobody cares.
>>
>> The value of the trick was acknowledged as now being in use
>> http://article.gmane.org/gmane.comp.version-control.git/223572
>
> How is that more useful than 'git branch -f master $sha1'?

The 'trick' checks for a fast forward, while the branch update is forced. It depends on what checks are desired.

My original patch was to simply document Git's dot repository capability that does not appear to be that well known. Let's not keep it as an Easter Egg.

Show 70 quoted lines
>
>> Not sure if that was the caring you were commenting on.
>
> My point is that nobody uses '.' as a remote. Yes, you can find the
> occasional esoteric person in the Git mailing list that might find
> some weird command useful, but that's the fringe user-base.
>
>>> You say it's "mistaken", but you are not the arbiter of truth; the
>>> fact that you say it's so doesn't make it so. It's just rhetoric.
>>>
>>> You haven't shown that it's indeed mistaken.
>>
>>
>> An aside: in some domains (e.g. Human Error taxonomy) a 'mistake' is 
>> a
>> planned action which later turns out to not be the action that would 
>> now
>> have, in retrospect, been chosen. The intent was good, but is later 
>> classed
>> (within the taxonomy) as a 'mistake'. (It is not related to 'blame').
>
> Yeah, that's what a mistake is, in my mind.
>
>> If I understand the extended thread correctly, the approach moved on 
>> and
>> alternatives were found, so in that sense the intent was good.
>
> No, the approach didn't move on, there are no better alternatives, the
> "intent" is irrelevant, the approach is good, there is no mistake.
>
> Junio simply ignored the fact that he was proven wrong.
>
> I still haven't received a response: which makes more sense?
>
> a)
>
> % git checkout svn-ext
> % git fetch
> From .
> * branch            master     -> FETCH_HEAD
> # oops
> % git fetch git-svn
> % git log ..FETCH_HEAD
> % git merge FETCH_HEAD
>
> b)
>
> % git checkout svn-ext
> % git fetch
> From git://git.kernel.org/pub/scm/git/git
>    680ed3e..de3a5c6  master     -> origin/master
> # oops
> % git fetch svn-ext
> % git log ..FETCH_HEAD
> % git merge FETCH_HEAD
>
> -- 
> Felipe Contreras
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
>
> -----
> No virus found in this message.
> Checked by AVG - www.avg.com
> Version: 2013.0.3343 / Virus Database: 3162/6344 - Release Date: 
> 05/21/13
>
Felipe Contreras· May 22, 2013, 22:15 UTC · re: Philip Oakley · lore

Re: [RFC/PATCH 2/2] doc: command line interface (cli) dot-repository dwimmery

On Wed, May 22, 2013 at 5:09 PM, Philip Oakley <philipoakley@iee.org> wrote:
> From: "Felipe Contreras" <felipe.contreras@gmail.com>
> Sent: Wednesday, May 22, 2013 12:03 AM
Show 9 quoted lines
>>> The value of the trick was acknowledged as now being in use
>>> http://article.gmane.org/gmane.comp.version-control.git/223572
>>
>>
>> How is that more useful than 'git branch -f master $sha1'?
>
>
> The 'trick' checks for a fast forward, while the branch update is forced. It
> depends on what checks are desired.

If that was truly useful, surely we could add an option for 'git branch' to do just that.

> My original patch was to simply document Git's dot repository capability
> that does not appear to be that well known. Let's not keep it as an Easter
> Egg.

I know, all I said is that I think nobody cares about that implementation detail. Instead of explaining to the user why Git has so many quirks, we should get rid of them and make it work more in line with users' expectations.

-- 
Felipe Contreras
Philip Oakley· Sep 13, 2013, 21:23 UTC · re: Philip Oakley · lore

[PATCH V2 0/3] Extend dot repository documentation

This is an update to my patch series on 19 May documenting the dot repository notation.

The earlier threads start at: $gmane/224870/ [0/2] Extend dot repository documentation $gmane/224868/ [1/2] config doc: add dot-repository note $gmane/224869/ [2/2] doc: command line interface (cli) dot-repository dwimmery

The base documentation is now the URLs section (first patch) as suggested by Jonathan, with a clarification in config(1) branch.<name>.remote, and finally a note in cli(7).

The patches can be squashed together if appropriate.

Philip --

Philip Oakley (3):
  Doc URLs: relative paths imply the dot-respository
  config doc: update dot-repository notes
  doc: command line interface (cli) dot-repository dwimmery
 Documentation/config.txt | 6 ++++--
 Documentation/gitcli.txt | 4 ++++
 Documentation/urls.txt   | 7 +++++++
 3 files changed, 15 insertions(+), 2 deletions(-)
-- 
1.8.1.msysgit.1
Philip Oakley· Sep 13, 2013, 21:23 UTC · re: Philip Oakley · lore

[PATCH V2 1/3] Doc URLs: relative paths imply the dot-respository

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/urls.txt | 7 +++++++
 1 file changed, 7 insertions(+)
Show changes to Documentation/urls.txt +7 −0
diff --git a/Documentation/urls.txt b/Documentation/urls.txt
index 9ccb246..5350a63 100644
--- a/Documentation/urls.txt
+++ b/Documentation/urls.txt
@@ -55,6 +55,13 @@ These two syntaxes are mostly equivalent, except the former implies
 --local option.
 endif::git-clone[]
 
+Relative paths are relative to the `$GIT_DIR`, thus the path:
+
+- '.'
+
+is the current repository and acts as if it were a repository
+named `'.'`.
+
 When Git doesn't know how to handle a certain transport protocol, it
 attempts to use the 'remote-<transport>' remote helper, if one
 exists. To explicitly request a remote helper, the following syntax

-- 
1.8.1.msysgit.1
Junio C Hamano· Sep 13, 2013, 22:21 UTC · re: Philip Oakley · lore

Re: [PATCH V2 1/3] Doc URLs: relative paths imply the dot-respository

Philip Oakley <philipoakley@iee.org> writes:
Show 14 quoted lines
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>  Documentation/urls.txt | 7 +++++++
>  1 file changed, 7 insertions(+)
>
> diff --git a/Documentation/urls.txt b/Documentation/urls.txt
> index 9ccb246..5350a63 100644
> --- a/Documentation/urls.txt
> +++ b/Documentation/urls.txt
> @@ -55,6 +55,13 @@ These two syntaxes are mostly equivalent, except the former implies
>  --local option.
>  endif::git-clone[]
>  
> +Relative paths are relative to the `$GIT_DIR`, thus the path:
Is it?
	git init src dst
        cd src
        git commit --allow-empty -m initial
        cd ../dst
        git fetch ../src HEAD:refs/heads/copy

would work, but if it is relative to $GIT_DIR, the last one would need to be written as

	git fetch ../../src HEAD:refs/heads/copy
wouldn't it?
Show 9 quoted lines
> +
> +- '.'
> +
> +is the current repository and acts as if it were a repository
> +named `'.'`.
> +
>  When Git doesn't know how to handle a certain transport protocol, it
>  attempts to use the 'remote-<transport>' remote helper, if one
>  exists. To explicitly request a remote helper, the following syntax
Philip Oakley· Sep 14, 2013, 20:47 UTC · re: Junio C Hamano · lore

Re: [PATCH V2 1/3] Doc URLs: relative paths imply the dot-respository

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Friday, September 13, 2013 11:21 PM
Show 21 quoted lines
> Philip Oakley <philipoakley@iee.org> writes:
>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>  Documentation/urls.txt | 7 +++++++
>>  1 file changed, 7 insertions(+)
>>
>> diff --git a/Documentation/urls.txt b/Documentation/urls.txt
>> index 9ccb246..5350a63 100644
>> --- a/Documentation/urls.txt
>> +++ b/Documentation/urls.txt
>> @@ -55,6 +55,13 @@ These two syntaxes are mostly equivalent, except 
>> the former implies
>>  --local option.
>>  endif::git-clone[]
>>
>> +Relative paths are relative to the `$GIT_DIR`, thus the path:
>
> Is it?
>
> git init src dst

I didn't think you could do that. It's not documented (initialise multiple dirctories with the same command) and on msysgit if fails with `usage:`. But I know what you mean.

Show 11 quoted lines
>        cd src
>        git commit --allow-empty -m initial
>        cd ../dst
>        git fetch ../src HEAD:refs/heads/copy
>
> would work, but if it is relative to $GIT_DIR, the last one would
> need to be written as
>
> git fetch ../../src HEAD:refs/heads/copy
>
> wouldn't it?

Ah but... we are specifying a repository here, not a file path, so the `$GIT_DIR` / '.git' discovery comes into it, I think. It's the discovery of the relevant repository that I now realise I've not included, which can be confusing in the various special cases. So the relative paths comment will be incomplete [your point], and needs something extra between "relative to" and "the $GIT_DIR".

Show 10 quoted lines
>
>> +
>> +- '.'
>> +
>> +is the current repository and acts as if it were a repository
>> +named `'.'`.
>> +
>>  When Git doesn't know how to handle a certain transport protocol, it
>>  attempts to use the 'remote-<transport>' remote helper, if one
>>  exists. To explicitly request a remote helper, the following syntax
Philip Oakley· Sep 13, 2013, 21:23 UTC · re: Philip Oakley · lore

[PATCH V2 2/3] config doc: update dot-repository notes

branch.<name>.remote can be set to '.' (period) as the repository path (URL) as part of the remote name dwimmery. Tell the reader.

Such relative paths are not 'special'. Correct the branch.<name>.merge note.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/config.txt | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)
Show changes to Documentation/config.txt +4 −2
diff --git a/Documentation/config.txt b/Documentation/config.txt
index 599ca52..da63043 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -718,6 +718,8 @@ branch.<name>.remote::
 	overridden by `branch.<name>.pushremote`.  If no remote is
 	configured, or if you are not on any branch, it defaults to
 	`origin` for fetching and `remote.pushdefault` for pushing.
+	Additionally, `.` (a period) is the current local repository
+	(a dot-repository), see `branch.<name>.merge`'s final note below.
 
 branch.<name>.pushremote::
 	When on branch <name>, it overrides `branch.<name>.remote` for
@@ -743,8 +745,8 @@ branch.<name>.merge::
 	Specify multiple values to get an octopus merge.
 	If you wish to setup 'git pull' so that it merges into <name> from
 	another branch in the local repository, you can point
-	branch.<name>.merge to the desired branch, and use the special setting
-	`.` (a period) for branch.<name>.remote.
+	branch.<name>.merge to the desired branch, and use the relative path
+	setting `.` (a period) for branch.<name>.remote.
 
 branch.<name>.mergeoptions::
 	Sets default options for merging into branch <name>. The syntax and

-- 
1.8.1.msysgit.1
Junio C Hamano· Sep 13, 2013, 22:28 UTC · re: Philip Oakley · lore

Re: [PATCH V2 2/3] config doc: update dot-repository notes

Philip Oakley <philipoakley@iee.org> writes:
Show 5 quoted lines
> branch.<name>.remote can be set to '.' (period) as the repository
> path (URL) as part of the remote name dwimmery. Tell the reader.
>
> Such relative paths are not 'special'. Correct the branch.<name>.merge
> note.
Looks good.
It naturally follows that this is also valid:
	[branch "master"]
        	merge = refs/heads/master
	        remote = git://git.kernel.org/pub/scm/git/git.git
and running "git pull" while on your 'master'.

This is because branch.<name>.remote usually is spelled with a nickname that refers to the [remote <nickname>] section, but it does not have to be; it can use a URL to refer to the remote repository.

Show 30 quoted lines
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>  Documentation/config.txt | 6 ++++--
>  1 file changed, 4 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/config.txt b/Documentation/config.txt
> index 599ca52..da63043 100644
> --- a/Documentation/config.txt
> +++ b/Documentation/config.txt
> @@ -718,6 +718,8 @@ branch.<name>.remote::
>  	overridden by `branch.<name>.pushremote`.  If no remote is
>  	configured, or if you are not on any branch, it defaults to
>  	`origin` for fetching and `remote.pushdefault` for pushing.
> +	Additionally, `.` (a period) is the current local repository
> +	(a dot-repository), see `branch.<name>.merge`'s final note below.
>  
>  branch.<name>.pushremote::
>  	When on branch <name>, it overrides `branch.<name>.remote` for
> @@ -743,8 +745,8 @@ branch.<name>.merge::
>  	Specify multiple values to get an octopus merge.
>  	If you wish to setup 'git pull' so that it merges into <name> from
>  	another branch in the local repository, you can point
> -	branch.<name>.merge to the desired branch, and use the special setting
> -	`.` (a period) for branch.<name>.remote.
> +	branch.<name>.merge to the desired branch, and use the relative path
> +	setting `.` (a period) for branch.<name>.remote.
>  
>  branch.<name>.mergeoptions::
>  	Sets default options for merging into branch <name>. The syntax and
Philip Oakley· Sep 14, 2013, 20:47 UTC · re: Junio C Hamano · lore

Re: [PATCH V2 2/3] config doc: update dot-repository notes

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Friday, September 13, 2013 11:28 PM
Subject: Re: [PATCH V2 2/3] config doc: update dot-repository notes
Show 52 quoted lines
> Philip Oakley <philipoakley@iee.org> writes:
>
>> branch.<name>.remote can be set to '.' (period) as the repository
>> path (URL) as part of the remote name dwimmery. Tell the reader.
>>
>> Such relative paths are not 'special'. Correct the 
>> branch.<name>.merge
>> note.
>
> Looks good.
>
> It naturally follows that this is also valid:
>
> [branch "master"]
>        merge = refs/heads/master
>         remote = git://git.kernel.org/pub/scm/git/git.git
>
> and running "git pull" while on your 'master'.
>
> This is because branch.<name>.remote usually is spelled with a
> nickname that refers to the [remote <nickname>] section, but it does
> not have to be; it can use a URL to refer to the remote repository.
>
>>
>> Signed-off-by: Philip Oakley <philipoakley@iee.org>
>> ---
>>  Documentation/config.txt | 6 ++++--
>>  1 file changed, 4 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/config.txt b/Documentation/config.txt
>> index 599ca52..da63043 100644
>> --- a/Documentation/config.txt
>> +++ b/Documentation/config.txt
>> @@ -718,6 +718,8 @@ branch.<name>.remote::
>>  overridden by `branch.<name>.pushremote`.  If no remote is
>>  configured, or if you are not on any branch, it defaults to
>>  `origin` for fetching and `remote.pushdefault` for pushing.
>> + Additionally, `.` (a period) is the current local repository
>> + (a dot-repository), see `branch.<name>.merge`'s final note below.
>>
>>  branch.<name>.pushremote::
>>  When on branch <name>, it overrides `branch.<name>.remote` for
>> @@ -743,8 +745,8 @@ branch.<name>.merge::
>>  Specify multiple values to get an octopus merge.
>>  If you wish to setup 'git pull' so that it merges into <name> from
>>  another branch in the local repository, you can point
>> - branch.<name>.merge to the desired branch, and use the special 
>> setting
>> - `.` (a period) for branch.<name>.remote.
>> + branch.<name>.merge to the desired branch, and use the relative 
>> path
>> + setting `.` (a period) for branch.<name>.remote.

This may need something extra because it doesn't say where it is relative to, nor comment on git_dir discovery (see patch 1 comments, likewise patch 3)

Show 8 quoted lines
>>
>>  branch.<name>.mergeoptions::
>>  Sets default options for merging into branch <name>. The syntax and
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>
Philip Oakley· Sep 13, 2013, 21:23 UTC · re: Philip Oakley · lore

[PATCH V2 3/3] doc: command line interface (cli) dot-repository dwimmery

The Git cli will accept dot '.' (period) as the relative path to the current repository. Explain this action.

Signed-off-by: Philip Oakley <philipoakley@iee.org>
---
 Documentation/gitcli.txt | 4 ++++
 1 file changed, 4 insertions(+)
Show changes to Documentation/gitcli.txt +4 −0
diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
index 7d54b77..b065c0e 100644
--- a/Documentation/gitcli.txt
+++ b/Documentation/gitcli.txt
@@ -58,6 +58,10 @@ the paths in the index that match the pattern to be checked out to your
 working tree.  After running `git add hello.c; rm hello.c`, you will _not_
 see `hello.c` in your working tree with the former, but with the latter
 you will.
++
+Just as the filesystem '.' (period) refers to the current directory,
+using a '.' as a repository name in Git (a dot-repository) is a relative
+path for your current repository.
 
 Here are the rules regarding the "flags" that you should follow when you are
 scripting Git:

-- 
1.8.1.msysgit.1
Junio C Hamano· Sep 13, 2013, 22:31 UTC · re: Philip Oakley · lore

Re: [PATCH V2 3/3] doc: command line interface (cli) dot-repository dwimmery

Philip Oakley <philipoakley@iee.org> writes:
Show 20 quoted lines
> The Git cli will accept dot '.' (period) as the relative path
> to the current repository. Explain this action.
>
> Signed-off-by: Philip Oakley <philipoakley@iee.org>
> ---
>  Documentation/gitcli.txt | 4 ++++
>  1 file changed, 4 insertions(+)
>
> diff --git a/Documentation/gitcli.txt b/Documentation/gitcli.txt
> index 7d54b77..b065c0e 100644
> --- a/Documentation/gitcli.txt
> +++ b/Documentation/gitcli.txt
> @@ -58,6 +58,10 @@ the paths in the index that match the pattern to be checked out to your
>  working tree.  After running `git add hello.c; rm hello.c`, you will _not_
>  see `hello.c` in your working tree with the former, but with the latter
>  you will.
> ++
> +Just as the filesystem '.' (period) refers to the current directory,
> +using a '.' as a repository name in Git (a dot-repository) is a relative
> +path for your current repository.
Looks good to me.  Thanks.

← back to recent threads