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

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

[Philip Oakley]

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

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

[Philip Oakley]

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(+)

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

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

[Jonathan Nieder]

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 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

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

[Junio C Hamano]

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.

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.

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

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Monday, May 20, 2013 6:50 PM
> 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.

>
> 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. 

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

[Philip Oakley]

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(+)

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

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

[Jonathan Nieder]

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

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

[Philip Oakley]

From: "Jonathan Nieder" <jrnieder@gmail.com>
Sent: Sunday, May 19, 2013 6:39 PM
> 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 

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

[Junio C Hamano]

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.

    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.

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

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Monday, May 20, 2013 6:55 PM
> 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.

>
>    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 

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

[Junio C Hamano]

"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...

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

[Philip Oakley]

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?

> 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.

>
>    [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.

>
> 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 

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

[Junio C Hamano]

"Philip Oakley" <philipoakley@iee.org> writes:

> 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.

>>> 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...

> 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

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

[Felipe Contreras]

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.

>> 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

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

[Philip Oakley]

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
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.

>
>>> 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

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

[Felipe Contreras]

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'?

> 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

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

[Junio C Hamano]

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.

"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.

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

[Felipe Contreras]

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).

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.

>     % 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.

>     # 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

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

[Junio C Hamano]

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.

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

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

[Felipe Contreras]

On Tue, May 21, 2013 at 7:50 PM, Junio C Hamano <gitster@pobox.com> wrote:
> 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

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

[Junio C Hamano]

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.

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".

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

[Felipe Contreras]

On Wed, May 22, 2013 at 11:50 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 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.

> 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.

> 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

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

[Philip Oakley]

From: "Felipe Contreras" <felipe.contreras@gmail.com>
Sent: Wednesday, May 22, 2013 12:03 AM
> 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.

>
>> 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
> 

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

[Felipe Contreras]

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

>>> 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

[PATCH V2 0/3] Extend dot repository documentation

[Philip Oakley]

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

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

[Philip Oakley]

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 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

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

[Junio C Hamano]

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
        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?

> +
> +- '.'
> +
> +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

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

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
Sent: Friday, September 13, 2013 11:21 PM
> 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.

>        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".

>
>> +
>> +- '.'
>> +
>> +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

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

[Philip Oakley]

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(-)

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

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

[Junio C Hamano]

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.
>  
>  branch.<name>.mergeoptions::
>  	Sets default options for merging into branch <name>. The syntax and

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

[Philip Oakley]

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


> 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)

>>
>>  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
> 

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

[Philip Oakley]

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.
 
 Here are the rules regarding the "flags" that you should follow when you are
 scripting Git:
-- 
1.8.1.msysgit.1

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

[Junio C Hamano]

Philip Oakley <philipoakley@iee.org> writes:

> 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.