[RFC] Triangular Workflow: user friendly full implementation

[RFC] Triangular Workflow: user friendly full implementation

[Jordan DE GEA]

We are working on full implementation of triangular workflow feature.
For now, the main options available are: 
	 - branch.<name>.pushRemote
	 - remote.pushDefault
And only setable by hands. 

As it can be difficult to understand, here is what we want to do. 


Context:
	- One main remote repository, e.g. git/git.
	- A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.
	- A local clone of me/git on the machine

Purposes:
	- the local branch master has to fetch to git/git by default
	- the local branch master has to push to me/git by default

Configuration wanted:
	- Add a remote to git/git e.g. `git remote add ...`
	- Set the fetch remote for branch as default. 

For now, we can do that by setting: 
	- branch.<name>.remote to git/git
	- branch.<name>.pushRemote to me/git
But many options set `branch.<name>.remote`, a suitable solution is to
implement an option for the fetch for example. 


Here is what we want to implement: 

1. 
	a. add the config var: remote.fetchDefault
	b. add the config var: branch.<name>.fetchRemote
	c. add `git fetch --set-default` in order to set remote.fetchDefault
	d. add `git fetch --set-remote` in order to set branch.<name>.fetchRemote
	e. add `git pull --set-default` in order to set remote.fetchDefault
	f. add `git pull --set-remote` in order to set branch.<name>.fetchRemote

2. 
	a. add `git push --set-default` in order to set remote.pushDefault
	b. add `git push --set-remote` in order to set branch.<name>.pushRemote


What's your opinion about this feature ?

Re: [RFC] Triangular Workflow: user friendly full implementation

[Matthieu Moy]

Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:

> Here is what we want to implement: 

Your message contains the word "implement" too many times. Before
thinking about implementation, think, and discuss, about the design.

If your message is intended to be a discussion on the design, then avoid
using "implementation" in the subject.

> 1. 
> 	a. add the config var: remote.fetchDefault
> 	b. add the config var: branch.<name>.fetchRemote
> 	c. add `git fetch --set-default` in order to set remote.fetchDefault
> 	d. add `git fetch --set-remote` in order to set branch.<name>.fetchRemote
> 	e. add `git pull --set-default` in order to set remote.fetchDefault
> 	f. add `git pull --set-remote` in order to set branch.<name>.fetchRemote
>
> 2. 
> 	a. add `git push --set-default` in order to set remote.pushDefault
> 	b. add `git push --set-remote` in order to set branch.<name>.pushRemote

This tells a lot about the "what?", but lacks the most important "why?"
(or "what for?") question.

The user doesn't want to "set configuration variables". He wants to work
with git, have commands do the right thing, avoid typing useless
keystrokes and avoid surprising behavior. Please explain how your
proposal would improve the situation. For example, show a typical
use-case with commands to type before and after your proposal is
implemented.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [RFC] Triangular Workflow: user friendly full implementation

[Junio C Hamano]

Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:

> We are working on full implementation of triangular workflow feature.
> For now, the main options available are: 
> 	 - branch.<name>.pushRemote
> 	 - remote.pushDefault
> And only setable by hands. 

And once it is set, you do not have to worry about it.  I am not
sure per-branch thing is all that useful, unless you are always
working on a single branch like 'master', but the latter would be
just set once and forget about it.

> Context:
> 	- One main remote repository, e.g. git/git.
> 	- A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.
> 	- A local clone of me/git on the machine
> Purposes:
> 	- the local branch master has to fetch to git/git by default
> 	- the local branch master has to push to me/git by default

Wouldn't remote.pushDefault be the single thing you need to set just
once and forget about it?  Why would your users even want to do
these things ...

> 	c. add `git fetch --set-default` in order to set remote.fetchDefault
> 	d. add `git fetch --set-remote` in order to set branch.<name>.fetchRemote
> 	e. add `git pull --set-default` in order to set remote.fetchDefault
> 	f. add `git pull --set-remote` in order to set branch.<name>.fetchRemote
> 	a. add `git push --set-default` in order to set remote.pushDefault
> 	b. add `git push --set-remote` in order to set branch.<name>.pushRemote

... just to configure many variables every time they work on a new
branch?

Re: [RFC] Triangular Workflow: user friendly full implementation

[Philip Oakley]

From: "Jordan DE GEA" <jordan.de-gea@grenoble-inp.org>
> We are working on full implementation of triangular workflow feature.
> For now, the main options available are:
> - branch.<name>.pushRemote
> - remote.pushDefault
> And only setable by hands.
>
> As it can be difficult to understand, here is what we want to do.
>
>
> Context:
> - One main remote repository, e.g. git/git.
> - A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.
> - A local clone of me/git on the machine
>
> Purposes:
> - the local branch master has to fetch to git/git by default
> - the local branch master has to push to me/git by default
>
> Configuration wanted:
> - Add a remote to git/git e.g. `git remote add ...`
> - Set the fetch remote for branch as default.
>
> For now, we can do that by setting:
> - branch.<name>.remote to git/git
> - branch.<name>.pushRemote to me/git
> But many options set `branch.<name>.remote`, a suitable solution is to
> implement an option for the fetch for example.
>
>
> Here is what we want to implement:
>
> 1.
> a. add the config var: remote.fetchDefault
> b. add the config var: branch.<name>.fetchRemote
> c. add `git fetch --set-default` in order to set remote.fetchDefault
> d. add `git fetch --set-remote` in order to set branch.<name>.fetchRemote
> e. add `git pull --set-default` in order to set remote.fetchDefault
> f. add `git pull --set-remote` in order to set branch.<name>.fetchRemote
>
> 2.
> a. add `git push --set-default` in order to set remote.pushDefault
> b. add `git push --set-remote` in order to set branch.<name>.pushRemote
>
>
> What's your opinion about this feature ?
>
For me, the first step would be to actually document a (the?) Triangular 
Workflow in the documentation, so we are all taking about the same broad 
method.

At the moment there is a choice (assuming a ithub like service) of either 
clone and then fork, or fork and clone the fork, which leave the user with 
different fixups of their config's being required, so describing the easier 
one would help folk.

Likewise there are missing terms such as for the third place (the personal 
fork) that is neither the upstream, nor the local repo. Making sure the 
terminology is crisp and clean will greatly ease any implementation issues. 
And then there are the possible workflows...

--
Philip
(sorry for the rushed message, a long weekend beckons) 

[RFC] Triangular Workflow UI improvement

[Jordan DE GEA]

In my last message, I forgot to add some important 
contributors linked to this feature. Some of you 
already replied to me. 
I will answer shortly. Sorry for the noise. 

> 
> We are working on full implementation of triangular workflow feature.
> For now, the main options available are: 
> 	 - branch.<name>.pushRemote
> 	 - remote.pushDefault
> And only setable by hands. 
> 
> As it can be difficult to understand, here is what we want to do. 
> 
> 
> Context:
> 	- One main remote repository, e.g. git/git.
> 	- A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.
> 	- A local clone of me/git on the machine
> 
> Purposes:
> 	- the local branch master has to fetch to git/git by default
> 	- the local branch master has to push to me/git by default
> 
> Configuration wanted:
> 	- Add a remote to git/git e.g. `git remote add ...`
> 	- Set the fetch remote for branch as default. 
> 
> For now, we can do that by setting: 
> 	- branch.<name>.remote to git/git
> 	- branch.<name>.pushRemote to me/git
> But many options set `branch.<name>.remote`, a suitable solution is to
> implement an option for the fetch for example. 
> 
> 
> Here is what we want to implement: 
> 
> 1. 
> 	a. add the config var: remote.fetchDefault
> 	b. add the config var: branch.<name>.fetchRemote
> 	c. add `git fetch --set-default` in order to set remote.fetchDefault
> 	d. add `git fetch --set-remote` in order to set branch.<name>.fetchRemote
> 	e. add `git pull --set-default` in order to set remote.fetchDefault
> 	f. add `git pull --set-remote` in order to set branch.<name>.fetchRemote
> 
> 2. 
> 	a. add `git push --set-default` in order to set remote.pushDefault
> 	b. add `git push --set-remote` in order to set branch.<name>.pushRemote
> 
> 
> What's your opinion about this feature ?

[RFC] Triangular Workflow UI improvement

[Jordan DE GEA]

>> We are working on full implementation of triangular workflow feature.
>> For now, the main options available are: 
>> 	 - branch.<name>.pushRemote
>> 	 - remote.pushDefault
>> And only setable by hands. 
> 
> And once it is set, you do not have to worry about it.  I am not
> sure per-branch thing is all that useful, unless you are always
> working on a single branch like 'master', but the latter would be
> just set once and forget about it.

We got the example of our fork of git(e.g. GitHub). 
We want : 
 - some branches that only fetch from git/git and push to our/git
 - the others branches fetch from and push to our/git. 
For now, we have to change branch.<name>.remote and 
branch.<name>.pushRemote(or remote.pushDefault). 
With branch.<name>.fetchRemote, we only have to set this one. 
fetchRemote is more explicit than remote for that case. 

Another point is that many commands can erase the old 
value of branch.<name>.remote. 

>> Context:
>> 	- One main remote repository, e.g. git/git.
>> 	- A remote fork (e.g. a GitHub fork) of git/git, e.g. me/git.
>> 	- A local clone of me/git on the machine
>> Purposes:
>> 	- the local branch master has to fetch to git/git by default
>> 	- the local branch master has to push to me/git by default
> 
> Wouldn't remote.pushDefault be the single thing you need to set just
> once and forget about it?  Why would your users even want to do
> these things …

remote.pushDefault overrides branch.<name>.remote for all branches. 
The goal is to give an easily understandable config for 
complex configuration. 
Having all the configuration in the same part (e.g [branch « master »]) 
is easier to understand and edit. 

> 
>> 	c. add `git fetch --set-default` in order to set remote.fetchDefault
>> 	d. add `git fetch --set-remote` in order to set branch.<name>.fetchRemote
>> 	e. add `git pull --set-default` in order to set remote.fetchDefault
>> 	f. add `git pull --set-remote` in order to set branch.<name>.fetchRemote
>> 	a. add `git push --set-default` in order to set remote.pushDefault
>> 	b. add `git push --set-remote` in order to set branch.<name>.pushRemote
> 
> ... just to configure many variables every time they work on a new
> branch?

branch.<name>.pushRemote and all these options are optional.
Options in commands may not be added. It just gives user 
friendly interaction with these options.  



To conclude: 
This feature is more about configuration clarity than possibility itself. 

[RFC] Triangular Workflow UI improvments

[Jordan DE GEA]

> Le 27 mai 2016 à 09:32, Philip Oakley <philipoakley@iee.org> a écrit :
> For me, the first step would be to actually document a (the?) Triangular Workflow in the documentation, so we are all taking about the same broad method.
> 
> At the moment there is a choice (assuming a ithub like service) of either clone and then fork, or fork and clone the fork, which leave the user with different fixups of their config's being required, so describing the easier one would help folk.
> 
> Likewise there are missing terms such as for the third place (the personal fork) that is neither the upstream, nor the local repo. Making sure the terminology is crisp and clean will greatly ease any implementation issues. And then there are the possible workflows...

Yes, you’re right. 

Writing a complete tutorial is a good idea. 

I start this job and the content will depend 
on the result of this discussion. 

[RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Jordan DE GEA]

Currently, Triangular Workflow can be configured, but there is no
Documentation about it. A documentation is useful to keep
configuration possibilities up-to-date.
The new documentation file gittriangularworkflow explains
how to configure a triangular workflow.

Signed-off-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
Signed-off-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
---
 Documentation/Makefile                  |   1 +
 Documentation/gittriangularworkflow.txt | 120 ++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+)
 create mode 100644 Documentation/gittriangularworkflow.txt

diff --git a/Documentation/Makefile b/Documentation/Makefile
index f6e288b..e9f6c80 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -34,6 +34,7 @@ MAN7_TXT += gitrevisions.txt
 MAN7_TXT += gittutorial-2.txt
 MAN7_TXT += gittutorial.txt
 MAN7_TXT += gitworkflows.txt
+MAN7_TXT += gittriangularworkflow.txt
 
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
 MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
diff --git a/Documentation/gittriangularworkflow.txt b/Documentation/gittriangularworkflow.txt
new file mode 100644
index 0000000..803eee3
--- /dev/null
+++ b/Documentation/gittriangularworkflow.txt
@@ -0,0 +1,120 @@
+gittriangularworkflow(7)
+=======================
+
+NAME
+----
+gittriangularworkflow - A tutorial about the configuration of a
+Triangular Workflow
+
+SYNOPSIS
+--------
+[verse]
+git fetch
+git remote
+git config
+Options in git-config:
+- `remote.pushDefault`
+- `branch.<branch>.pushRemote`
+- `branch.<branch>.origin`
+
+DESCRIPTION
+-----------
+
+Triangular Workflow (or Asymmetric Workflow) is a workflow which gives
+the possibility to:
+
+- fetch (or pull) from a repository
+- push to another repository
+
+In some projects, you don't have to push directly to the project but
+have to suggest your commits to the maintainer (e.g. pull requests).
+Using Triangular Workflow is a common way for these projects.
+
+This document attempts to help you configure a Triangular Workflow.
+Here is an example of configuration:
+
+........................................
+------------               -----------
+| UPSTREAM |  maintainer   | ORIGIN  |
+|  git/git |- - - - - - - -|  me/git |
+------------       ←       -----------
+         \                   /
+          \                 /
+     fetch↓\               /↑push
+            \             /
+             \           /
+             -------------
+             |   LOCAL   |
+             -------------
+........................................
+
+CREATE YOUR REPOSITORY
+----------------------
+The first step is to create your own repository. To do that you can:
+
+- a. fork (e.g. GitHub) the main project (e.g git/git), or
+- b. create an empty repository
+
+a. Fork the project
+~~~~~~~~~~~~~~~~~~~
+Go to the repository of the project (e.g. git/git) you want
+and fork it.
+
+b. Create from scratch
+~~~~~~~~~~~~~~~~~~~~~~
+Create a repository on your prefered Git repository hosting service.
+
+Clone it
+~~~~~~~~
+Clone your repository on your machine.
+
+
+CONFIGURE BRANCHES
+------------------
+In many projects, the branch `master` have to be pulled from
+the main repository(e.g. git/git) and pushed to your repository
+(e.g. me/git).
+
+Adding the main project remote
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add a new remote (e.g. upstream):
+
+===================================
+`git remote add upstream <main_project_url>`
+===================================
+
+Pull from upstream by default
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+===================================
+`git config branch.master.remote upstream`
+===================================
+
+
+Push to origin by default
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+===================================
+`git config branch.master.pushRemote origin`
+===================================
+
+
+GET YOUR PROJECT UP TO DATE
+---------------------------
+
+Now that `branch.master.remote` and `branch.master.pushRemote` are
+set, you can use the following commands to be up to date:
+=====================================
+ * `git pull`
+ * `git push`
+=====================================
+
+
+SEE ALSO
+--------
+linkgit:git-config[1]
+linkgit:git-remote[1]
+linkgit:git-fetch[1]
+
+
+
-- 
2.7.4 (Apple Git-66)

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Matthieu Moy]

[ +Cc Michael Haggerty ]

Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:

> Currently, Triangular Workflow can be configured, but there is no
> Documentation about it. A documentation is useful to keep
> configuration possibilities up-to-date.

You're using capitalization in a strange way. I don't think Triangular
Workflow deserves to be capitalized, and Documentation certainly
doesn't.

Also, you're wrapping your text in a strange way. You did see the
exchange with Antoine about this, right?

A question about your final goal: I had understood that you wanted to
improve the UI, and to design a proper UI you wanted to write a tutorial
about the future UI, and then implement it. Did I mis-understand? What
are the next steps in your plan?

>  Documentation/Makefile                  |   1 +
>  Documentation/gittriangularworkflow.txt | 120 ++++++++++++++++++++++++++++++++
[...]
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -34,6 +34,7 @@ MAN7_TXT += gitrevisions.txt
>  MAN7_TXT += gittutorial-2.txt
>  MAN7_TXT += gittutorial.txt
>  MAN7_TXT += gitworkflows.txt
> +MAN7_TXT += gittriangularworkflow.txt

Adding documentation is one thing, but it needs to be discoverable. No
one is going to type "man gittriangularworkflow" or open
https://git-scm.com/docs/gittriangularworkflow without being told to.

Two obvious questions/suggestions seeing the above:

* Why not add the new documentation as a subsection of gitworkflows.txt?

* If not, then at the very least a link to gittriangularworkflow should
  appear in the SEE ALSO section of gitworkflows.txt.

> +DESCRIPTION
> +-----------
> +
> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives
> +the possibility to:
> +
> +- fetch (or pull) from a repository
> +- push to another repository

I wouldn't say "gives the possibility to": you already have this
possibility all the time when using Git.

I find Michael Haggerty's definition of triangular workflow much
clearer:

https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows#improved-support-for-triangular-workflows

I don't see a licence on the GitHub blog, so I don't think it's legal to
copy-past directly to our docs, but Michael might allow us to do so?

> +In some projects, you don't have to push directly

s/don't have to/cannot/

?

> +Here is an example of configuration:
> +
> +........................................
> +------------               -----------
> +| UPSTREAM |  maintainer   | ORIGIN  |
> +|  git/git |- - - - - - - -|  me/git |
> +------------       ←       -----------
> +         \                   /
> +          \                 /
> +     fetch↓\               /↑push
> +            \             /
> +             \           /
> +             -------------
> +             |   LOCAL   |
> +             -------------
> +........................................

The most important is missing: what is the role of each repo? which one
is public and which one is private?

I'd rather avoid using "ORIGIN" here, as the name is used for the
default remote when cloning, and it's a valid workflow to "git clone"
from UPSTREAM and then "git remote add" your public fork. Perhaps
PUBLIC-FORK?

> +CREATE YOUR REPOSITORY
> +----------------------
> +The first step is to create your own repository. To do that you can:
> +
> +- a. fork (e.g. GitHub) the main project (e.g git/git), or
> +- b. create an empty repository
> +
> +a. Fork the project
> +~~~~~~~~~~~~~~~~~~~
> +Go to the repository of the project (e.g. git/git) you want
> +and fork it.
> +
> +b. Create from scratch
> +~~~~~~~~~~~~~~~~~~~~~~
> +Create a repository on your prefered Git repository hosting service.
> +
> +Clone it
> +~~~~~~~~
> +Clone your repository on your machine.

I don't think this section helps much. If the user knows that he or she
wants to "fork (e.g. GitHub) the main project (e.g git/git),", then
saying

  +a. Fork the project
  +~~~~~~~~~~~~~~~~~~~
  +Go to the repository of the project (e.g. git/git) you want
  +and fork it.

does not help at all, it just says the same thing in a more verbose way.

> +CONFIGURE BRANCHES
> +------------------
> +In many projects, the branch `master` have to be pulled from
> +the main repository(e.g. git/git) and pushed to your repository
> +(e.g. me/git).

Be precise: you just named 3 repositories UPSTREAM, ORIGIN and LOCAL,
and now you're writting "the main repository" (not 100% clear) and "your
repository" (100% not clear, you have two repos).

Actually, most of the time, you'd pull from UPSTREAM/master and push to
PUBLIC-FORK/<topic-branch>, not PUBLIC-FORK/master.

> +Adding the main project remote
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Add a new remote (e.g. upstream):
> +
> +===================================
> +`git remote add upstream <main_project_url>`
> +===================================
> +
> +Pull from upstream by default
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +===================================
> +`git config branch.master.remote upstream`
> +===================================
> +
> +
> +Push to origin by default
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +===================================
> +`git config branch.master.pushRemote origin`
> +===================================

"by default" probably needs to be clarified ("when push/pull is called
without argument"?)

> +GET YOUR PROJECT UP TO DATE
> +---------------------------
> +
> +Now that `branch.master.remote` and `branch.master.pushRemote` are
> +set, you can use the following commands to be up to date:

What does "be up to date" mean?

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Jordan DE GEA]

> Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:
>> Currently, Triangular Workflow can be configured, but there is no
>> Documentation about it. A documentation is useful to keep
>> configuration possibilities up-to-date.
> 
> You're using capitalization in a strange way. I don't think Triangular
> Workflow deserves to be capitalized, and Documentation certainly
> doesn't.
> 
> Also, you're wrapping your text in a strange way. You did see the
> exchange with Antoine about this, right?

Yes, thank you. I will fix that. 

> A question about your final goal: I had understood that you wanted to
> improve the UI, and to design a proper UI you wanted to write a tutorial
> about the future UI, and then implement it. Did I mis-understand? What
> are the next steps in your plan?

The first goal is to write a documentation on "how to set up a triangular
workflow" with the current options. After that, we can discuss about the
UI improvement. 

>> Documentation/Makefile                  |   1 +
>> Documentation/gittriangularworkflow.txt | 120 ++++++++++++++++++++++++++++++++
> [...]
>> --- a/Documentation/Makefile
>> +++ b/Documentation/Makefile
>> @@ -34,6 +34,7 @@ MAN7_TXT += gitrevisions.txt
>> MAN7_TXT += gittutorial-2.txt
>> MAN7_TXT += gittutorial.txt
>> MAN7_TXT += gitworkflows.txt
>> +MAN7_TXT += gittriangularworkflow.txt
> 
> Adding documentation is one thing, but it needs to be discoverable. No
> one is going to type "man gittriangularworkflow" or open
> https://git-scm.com/docs/gittriangularworkflow without being told to.
> 
> Two obvious questions/suggestions seeing the above:
> 
> * Why not add the new documentation as a subsection of gitworkflows.txt?
> 
> * If not, then at the very least a link to gittriangularworkflow should
>  appear in the SEE ALSO section of gitworkflows.txt.

Yes, adding a subsection in gitworkflows seems to be a better choice.

> 
>> +DESCRIPTION
>> +-----------
>> +
>> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives
>> +the possibility to:
>> +
>> +- fetch (or pull) from a repository
>> +- push to another repository
> 
> I wouldn't say "gives the possibility to": you already have this
> possibility all the time when using Git.
> 
> I find Michael Haggerty's definition of triangular workflow much
> clearer:
> 
> https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows#improved-support-for-triangular-workflows
> 
> I don't see a licence on the GitHub blog, so I don't think it's legal to
> copy-past directly to our docs, but Michael might allow us to do so?

You’re right. Can Michael Taggerty allow us to use his text ?

> 
>> +In some projects, you don't have to push directly
> 
> s/don't have to/cannot/

Done

> ?
> 
>> +Here is an example of configuration:
>> +
>> +........................................
>> +------------               -----------
>> +| UPSTREAM |  maintainer   | ORIGIN  |
>> +|  git/git |- - - - - - - -|  me/git |
>> +------------       ←       -----------
>> +         \                   /
>> +          \                 /
>> +     fetch↓\               /↑push
>> +            \             /
>> +             \           /
>> +             -------------
>> +             |   LOCAL   |
>> +             -------------
>> +........................................
> 
> The most important is missing: what is the role of each repo? which one
> is public and which one is private?
> 
> I'd rather avoid using "ORIGIN" here, as the name is used for the
> default remote when cloning, and it's a valid workflow to "git clone"
> from UPSTREAM and then "git remote add" your public fork. Perhaps
> PUBLIC-FORK?

With Michael Taggerty’s text, it will be more understandable. 

> 
>> +CREATE YOUR REPOSITORY
>> +----------------------
>> +The first step is to create your own repository. To do that you can:
>> +
>> +- a. fork (e.g. GitHub) the main project (e.g git/git), or
>> +- b. create an empty repository
>> +
>> +a. Fork the project
>> +~~~~~~~~~~~~~~~~~~~
>> +Go to the repository of the project (e.g. git/git) you want
>> +and fork it.
>> +
>> +b. Create from scratch
>> +~~~~~~~~~~~~~~~~~~~~~~
>> +Create a repository on your prefered Git repository hosting service.
>> +
>> +Clone it
>> +~~~~~~~~
>> +Clone your repository on your machine.
> 
> I don't think this section helps much. If the user knows that he or she
> wants to "fork (e.g. GitHub) the main project (e.g git/git),", then
> saying
> 
>  +a. Fork the project
>  +~~~~~~~~~~~~~~~~~~~
>  +Go to the repository of the project (e.g. git/git) you want
>  +and fork it.
> 
> does not help at all, it just says the same thing in a more verbose way.

I will shorten for the next iteration. 

>> +CONFIGURE BRANCHES
>> +------------------
>> +In many projects, the branch `master` have to be pulled from
>> +the main repository(e.g. git/git) and pushed to your repository
>> +(e.g. me/git).
> 
> Be precise: you just named 3 repositories UPSTREAM, ORIGIN and LOCAL,
> and now you're writting "the main repository" (not 100% clear) and "your
> repository" (100% not clear, you have two repos).
> 
> Actually, most of the time, you'd pull from UPSTREAM/master and push to
> PUBLIC-FORK/<topic-branch>, not PUBLIC-FORK/master.
> 
>> +Adding the main project remote
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +Add a new remote (e.g. upstream):
>> +
>> +===================================
>> +`git remote add upstream <main_project_url>`
>> +===================================
>> +
>> +Pull from upstream by default
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +===================================
>> +`git config branch.master.remote upstream`
>> +===================================
>> +
>> +
>> +Push to origin by default
>> +~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +===================================
>> +`git config branch.master.pushRemote origin`
>> +===================================
> 
> "by default" probably needs to be clarified ("when push/pull is called
> without argument »?)

Yes, that is too verbose. 

> 
>> +GET YOUR PROJECT UP TO DATE
>> +---------------------------
>> +
>> +Now that `branch.master.remote` and `branch.master.pushRemote` are
>> +set, you can use the following commands to be up to date:
> 
> What does "be up to date" mean?

OK. 


I'll work on these issues and send a new RFC soon. 

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Michael Haggerty]

On 05/31/2016 04:33 PM, Matthieu Moy wrote:
> Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:
> [...]
>> +DESCRIPTION
>> +-----------
>> +
>> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives
>> +the possibility to:
>> +
>> +- fetch (or pull) from a repository
>> +- push to another repository
> 
> [...]
> 
> I find Michael Haggerty's definition of triangular workflow much
> clearer:
> 
> https://github.com/blog/2042-git-2-5-including-multiple-worktrees-and-triangular-workflows#improved-support-for-triangular-workflows
> 
> I don't see a licence on the GitHub blog, so I don't think it's legal to
> copy-past directly to our docs, but Michael might allow us to do so?

I'm glad you find that blog post useful!

You are correct that the text of GitHub blog posts is copyrighted, so
indeed you need to ask before using it.

It is OK with me (and more importantly with GitHub, because I wrote this
text in their employ) for you to use the text about triangular workflows
from the blog post mentioned above under the Git project's license.

I strongly suggest that you adapt it to make it fit better with the rest
of the Git documentation, and because having verbatim copies of the same
text in two places seems a little bit silly. But that's up to you.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>

Michael

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Philip Oakley]

[Just catching up with responses]

From: "Jordan DE GEA" <jordan.de-gea@grenoble-inp.org>
Sent: Tuesday, May 31, 2016 1:28 PM
> Currently, Triangular Workflow can be configured, but there is no
> Documentation about it. A documentation is useful to keep
> configuration possibilities up-to-date.
> The new documentation file gittriangularworkflow explains
> how to configure a triangular workflow.
>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
> Signed-off-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
> ---
> Documentation/Makefile                  |   1 +
> Documentation/gittriangularworkflow.txt | 120 
> ++++++++++++++++++++++++++++++++
> 2 files changed, 121 insertions(+)
> create mode 100644 Documentation/gittriangularworkflow.txt
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index f6e288b..e9f6c80 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -34,6 +34,7 @@ MAN7_TXT += gitrevisions.txt
> MAN7_TXT += gittutorial-2.txt
> MAN7_TXT += gittutorial.txt
> MAN7_TXT += gitworkflows.txt
> +MAN7_TXT += gittriangularworkflow.txt
>
> MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
> MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
> diff --git a/Documentation/gittriangularworkflow.txt 
> b/Documentation/gittriangularworkflow.txt
> new file mode 100644
> index 0000000..803eee3
> --- /dev/null
> +++ b/Documentation/gittriangularworkflow.txt
> @@ -0,0 +1,120 @@
> +gittriangularworkflow(7)
> +=======================
> +
> +NAME
> +----
> +gittriangularworkflow - A tutorial about the configuration of a
> +Triangular Workflow
> +
> +SYNOPSIS
> +--------
> +[verse]
> +git fetch
> +git remote
> +git config
> +Options in git-config:
> +- `remote.pushDefault`
> +- `branch.<branch>.pushRemote`
> +- `branch.<branch>.origin`
> +
> +DESCRIPTION
> +-----------
> +
> +Triangular Workflow (or Asymmetric Workflow) is a workflow which gives
> +the possibility to:
> +
> +- fetch (or pull) from a repository
> +- push to another repository
> +
> +In some projects, you don't have to push directly to the project but
> +have to suggest your commits to the maintainer (e.g. pull requests).
> +Using Triangular Workflow is a common way for these projects.
> +
> +This document attempts to help you configure a Triangular Workflow.
> +Here is an example of configuration:
> +
> +........................................
> +------------               -----------
> +| UPSTREAM |  maintainer   | ORIGIN  |

UPSTREAM and ORIGIN are two different types of description. Origin being a 
too generic Git name that is used multiply elsewhere.

That said, trying to find a good name for that 'third place' is not easy. 
It's neither upstream, nor downstream (for Junio - the maintainer special 
case - git.git would be his downstream). The me/git repo is like a 
ferryman's landing across the other side of the river flow, a safe harbour 
if you will.

Finding a suitable name has all the same issues as deciding the generic 
public name for the staging area / index. The ability to have a second 
perfect copy is very new - historically all the dictionary names relate to 
copies or forgeries (you could only have one master - DVCS breaks that 
mould). Perhaps (poorly) "MyFork", or "MyServer". There maybe a good French 
word we can use.

> +|  git/git |- - - - - - - -|  me/git |

I think it is good to reference the use of "me" as a short remote name - 
personally I ended up using "my"/remote, but having one in the documentation 
will set a common trend.

> +------------       ←       -----------
> +         \                   /
> +          \                 /
> +     fetch↓\               /↑push
> +            \             /
> +             \           /
> +             -------------
> +             |   LOCAL   |
> +             -------------
> +........................................
> +
> +CREATE YOUR REPOSITORY
> +----------------------
> +The first step is to create your own repository. To do that you can:
> +
> +- a. fork (e.g. GitHub) the main project (e.g git/git), or
> +- b. create an empty repository
> +
> +a. Fork the project
> +~~~~~~~~~~~~~~~~~~~
> +Go to the repository of the project (e.g. git/git) you want
> +and fork it.

As I understand it one issue is to clearly suggest that it is best to fork 
and then clone from your me/fork project such that the origin and it's 
fetch/push are set up the easiest way.

If the user clones the main project before forking and then tries to add the 
me/fork there are more hoops to jump through to get all the fetch/push 
settings re-arranged (this does depend on the Github fork method, but at 
least the issue of which repo is cloned should be noted)

> +
> +b. Create from scratch
> +~~~~~~~~~~~~~~~~~~~~~~
> +Create a repository on your prefered Git repository hosting service.
> +
> +Clone it
> +~~~~~~~~
> +Clone your repository on your machine.
> +
> +
> +CONFIGURE BRANCHES
> +------------------
> +In many projects, the branch `master` have to be pulled from
> +the main repository(e.g. git/git) and pushed to your repository
> +(e.g. me/git).
> +
> +Adding the main project remote
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +Add a new remote (e.g. upstream):
> +
> +===================================
> +`git remote add upstream <main_project_url>`
> +===================================
> +
> +Pull from upstream by default
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +===================================
> +`git config branch.master.remote upstream`
> +===================================
> +
> +
> +Push to origin by default
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +===================================
> +`git config branch.master.pushRemote origin`
> +===================================
> +
> +
> +GET YOUR PROJECT UP TO DATE
> +---------------------------
> +
> +Now that `branch.master.remote` and `branch.master.pushRemote` are
> +set, you can use the following commands to be up to date:
> +=====================================
> + * `git pull`
> + * `git push`
> +=====================================
> +
> +
> +SEE ALSO
> +--------
> +linkgit:git-config[1]
> +linkgit:git-remote[1]
> +linkgit:git-fetch[1]
> +
> +
> +
> -- 
> 2.7.4 (Apple Git-66)
>
> 

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Jordan DE GEA]

> From: "Jordan DE GEA" <jordan.de-gea@grenoble-inp.org>
>> This document attempts to help you configure a Triangular Workflow.
>> +Here is an example of configuration:
>> +
>> +........................................
>> +------------               -----------
>> +| UPSTREAM |  maintainer   | ORIGIN  |
> 
> UPSTREAM and ORIGIN are two different types of description. Origin being a too generic Git name that is used multiply elsewhere.
> 
> That said, trying to find a good name for that 'third place' is not easy. It's neither upstream, nor downstream (for Junio - the maintainer special case - git.git would be his downstream). The me/git repo is like a ferryman's landing across the other side of the river flow, a safe harbour if you will.
> 
> Finding a suitable name has all the same issues as deciding the generic public name for the staging area / index. The ability to have a second perfect copy is very new - historically all the dictionary names relate to copies or forgeries (you could only have one master - DVCS breaks that mould). Perhaps (poorly) "MyFork", or "MyServer". There maybe a good French word we can use.
> 


You’re right, finding a good name is not easy. 
Firstly, I wanted to use DOWNSTREAM and UPSTREAM. But git doesn’t make the difference between those words.  

Looking for the description of the third place, I wrote that it’s the remote used to push modifications. 
Assembling the main words push and remote, it creates PUSH_REMOTE which seems a good name. 
e.g. That’s clear to say "I push to the push_remote".   

As the option `branch.<branch>.pushRemote` exists, a little text has to be added in order to prevent confusion. 
By the way, in the documentation, confusions will be avoided by using `branch.<name>.pushRemote` and ‘push_remote`.

Like PUSH_REMOTE, the remote where we fetch can be called FETCH_REMOTE. 
e.g. That’s clear to say "I fetch from fetch_remote". 

Do you agree?


> 
>> +------------       ←       -----------
>> +         \                   /
>> +          \                 /
>> +     fetch↓\               /↑push
>> +            \             /
>> +             \           /
>> +             -------------
>> +             |   LOCAL   |
>> +             -------------
>> +........................................
>> +
>> +CREATE YOUR REPOSITORY
>> +----------------------
>> +The first step is to create your own repository. To do that you can:
>> +
>> +- a. fork (e.g. GitHub) the main project (e.g git/git), or
>> +- b. create an empty repository
>> +
>> +a. Fork the project
>> +~~~~~~~~~~~~~~~~~~~
>> +Go to the repository of the project (e.g. git/git) you want
>> +and fork it.
> 
> As I understand it one issue is to clearly suggest that it is best to fork and then clone from your me/fork project such that the origin and it's fetch/push are set up the easiest way.
> 
> If the user clones the main project before forking and then tries to add the me/fork there are more hoops to jump through to get all the fetch/push settings re-arranged (this does depend on the Github fork method, but at least the issue of which repo is cloned should be noted)
Thank you, I will work on it. 

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Matthieu Moy]

Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:

> You’re right, finding a good name is not easy. 
> Firstly, I wanted to use DOWNSTREAM and UPSTREAM. But git doesn’t make the difference between those words.  

In english, "downstream" and "upstream" are relative terms. If A is
upstream compared to B, then B is downstream compared to A.

In terms of Git, you know what your upstream is (i.e. where you get
commits from), but you don't necessarily know what your downstream is
(i.e. who pulls from your repository). So, "downstream" wouldn't make
sense in a config file.

> Like PUSH_REMOTE, the remote where we fetch can be called FETCH_REMOTE. 
> e.g. That’s clear to say "I fetch from fetch_remote". 
>
> Do you agree?

That is technically correct, but to illustrate the overall flow, I'd
rather avoid naming the repositories in terms of git commands. If you do
so, you will probably end up with tautological explanations like this
later in the text: "FETCH_REMOTE is the remote from where you fetch,
PUSH_REMOTE is the remote to which you push, and LOCAL is local".

I suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I
think it translates the intent better than PUSH_REMOTE. An alternative
would be PUBLISH (= the repository you use to publish your changes so
that the maintainer can pick them).

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Jordan DE GEA]

>> Like PUSH_REMOTE, the remote where we fetch can be called FETCH_REMOTE. 
>> e.g. That’s clear to say "I fetch from fetch_remote". 
>> 
>> Do you agree?
> 
> That is technically correct, but to illustrate the overall flow, I'd
> rather avoid naming the repositories in terms of git commands. If you do
> so, you will probably end up with tautological explanations like this
> later in the text: "FETCH_REMOTE is the remote from where you fetch,
> PUSH_REMOTE is the remote to which you push, and LOCAL is local".
> 
> I suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I
> think it translates the intent better than PUSH_REMOTE. An alternative
> would be PUBLISH (= the repository you use to publish your changes so
> that the maintainer can pick them).

PUBLISH sounds good. I take it for the next patch. 

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Junio C Hamano]

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

> That said, trying to find a good name for that 'third place' is not easy. 
> It's neither upstream, nor downstream (for Junio - the maintainer special 
> case - git.git would be his downstream). The me/git repo is like a 
> ferryman's landing across the other side of the river flow, a safe harbour 
> if you will.

You raise a good point here.

To me, the git.git public repository that everybody pulls from is
just like me/git for everybody else.  It is a place where you
publish your work.  I think the @{push} notation during its design
phase was once called @{publish} instead.

A "downstream" that is the opposite of "upstream" is not something
you would configure and control.  They are those who call you
"upstream".  You know and actively configure who your "upstream" is
and pull from there.  You do not have direct control who are the
people who are pulling from you.

So in that sense, "downstream" exists as a concept that is just as
valid as "upstream", but unlike "upstream", "downstream" does not
manifest itself as something you explicitly tell Git about, either
from the command line, in the remotes definition, or in the
configuration files.

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> That said, trying to find a good name for that 'third place' is not easy.
>> It's neither upstream, nor downstream (for Junio - the maintainer special
>> case - git.git would be his downstream). The me/git repo is like a
>> ferryman's landing across the other side of the river flow, a safe 
>> harbour
>> if you will.
>
> You raise a good point here.
>
> To me, the git.git public repository that everybody pulls from is
> just like me/git for everybody else.  It is a place where you
> publish your work.  I think the @{push} notation during its design
> phase was once called @{publish} instead.

I'd agree that your git/git is actually an @{publish} repo, and to my mind 
is a formal 'downstream' for you.

However your gitster/git repo feels like it would match the me/git 
viewpoint, in that while it  is 'open', it isn't really a formal publishing 
place. Certainly I don't think that I 'publish' what's in my personal github 
repos, which I use as an open backup (and any PR's I put to the G4W project 
repo are referenced from there).

I did have a look at various thesaurus words 
(//www.thesaurus.com/browse/repository) that might be usable and found:-
depot, haven, shelter, sanctuary, wharf, bunker, vault, which are all 'near' 
but not quite right, if only home-depot wasn't taken I'd suggest that!

>
> A "downstream" that is the opposite of "upstream" is not something
> you would configure and control.  They are those who call you
> "upstream".  You know and actively configure who your "upstream" is
> and pull from there.  You do not have direct control who are the
> people who are pulling from you.
>
> So in that sense, "downstream" exists as a concept that is just as
> valid as "upstream", but unlike "upstream", "downstream" does not
> manifest itself as something you explicitly tell Git about, either
> from the command line, in the remotes definition, or in the
> configuration files.

Certainly for contributors, a configured 'downstream' repo doesn't make 
sense, but I do think it's worthwhile for maintainers, Leiutenants, and 
dictators who do have a specific publishing place. 

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Jordan DE GEA]

> Matthieu Moy <matthieu.moy@grenoble-inp.fr> a écrit :
> 
> That is technically correct, but to illustrate the overall flow, I'd
> rather avoid naming the repositories in terms of git commands. If you do
> so, you will probably end up with tautological explanations like this
> later in the text: "FETCH_REMOTE is the remote from where you fetch,
> PUSH_REMOTE is the remote to which you push, and LOCAL is local".
> 
> I suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I
> think it translates the intent better than PUSH_REMOTE. An alternative
> would be PUBLISH (= the repository you use to publish your changes so
> that the maintainer can pick them).

> "Philip Oakley" <philipoakley@iee.org> writes:
> However your gitster/git repo feels like it would match the me/git viewpoint, in that while it  is 'open', it isn't really a formal publishing place. Certainly I don't think that I 'publish' what's in my personal github repos, which I use as an open backup (and any PR's I put to the G4W project repo are referenced from there).


For Philip Oakley, PUBLISH seems to not be a good name. 
For PUBLIC-FORK, a fork can be private so I think that’s not a good idea. 

As the third-place is the repository used to work on commits/patches, 
a simple name can be WORK_REPOSITORY. 

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Matthieu Moy]

Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:

>> Matthieu Moy <matthieu.moy@grenoble-inp.fr> a écrit :
>> 
>> That is technically correct, but to illustrate the overall flow, I'd
>> rather avoid naming the repositories in terms of git commands. If you do
>> so, you will probably end up with tautological explanations like this
>> later in the text: "FETCH_REMOTE is the remote from where you fetch,
>> PUSH_REMOTE is the remote to which you push, and LOCAL is local".
>> 
>> I suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I
>> think it translates the intent better than PUSH_REMOTE. An alternative
>> would be PUBLISH (= the repository you use to publish your changes so
>> that the maintainer can pick them).
>
>> "Philip Oakley" <philipoakley@iee.org> writes:
>> However your gitster/git repo feels like it would match the me/git
>> viewpoint, in that while it is 'open', it isn't really a formal
>> publishing place. Certainly I don't think that I 'publish' what's in
>> my personal github repos, which I use as an open backup (and any
>> PR's I put to the G4W project repo are referenced from there).
>
>
> For Philip Oakley, PUBLISH seems to not be a good name. 
> For PUBLIC-FORK, a fork can be private so I think that’s not a good idea. 

I don't think you will find a name that fits all use-cases. IHMO, best
is to pick one rather general use-case, make the explanations for it,
and maybe explain somewhere that there are variants.

If the fork is completely private, then your diagram with a "maintainer"
arrow from it to upstream is not valid. It needs at least to be visible
to the maintainer. "public" may be a bit strong as you don't need to
make it "public" to everyone on earth, but to me that's OK to describe
the use-case.

> As the third-place is the repository used to work on commits/patches, 
> a simple name can be WORK_REPOSITORY.

"WORK" is already used to describe "worktree" which is precisely not
this repository. I don't "work" on my public fork, I "work" locally and
then just send commits there.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

[RFC/PATCHv2] Documentation: triangular workflow

[Jordan DE GEA]

Currently, triangular workflow can be configured, but there is no
documentation about it. A documentation is useful to keep
configuration possibilities up-to-date.

A new subsection is created in gitworkflow.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
Signed-off-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
---

Changes since version 1:
 - content moved in gitworktree
 - content improved

 Documentation/gitworkflows.txt | 155 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index f16c414..cd77893 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -463,6 +463,157 @@ if you get conflicts: `git am -3` will use index information contained
 in patches to figure out the merge base.  See linkgit:git-am[1] for
 other options.
 
+TRIANGULAR WORKFLOW
+-------------------
+
+In some projects, you cannot push directly to the project but have to
+suggest your commits to the maintainer (e.g. pull requests).
+For these projects, it's common to use what's called a *triangular
+workflow*:
+
+- Taking the last version of the project by fetching (e.g.
+  **UPSTREAM**)
+- Writing modifications and push them to a fork (e.g. **PUBLIC-FORK**)
+- Opening a pull request
+- Checking of changes by the maintainer and, merging them into the
+  **UPSTREAM** repository if accepted
+
+
+........................................
+------------------               -----------------
+| UPSTREAM       |  maintainer   | PUBLIC-FORK   |
+|  git/git       |- - - - - - - -|  me/remote    |
+------------------       ←       -----------------
+              \                     /
+               \                   /
+          fetch↓\                 /↑push
+                 \               /
+                  \             /
+                   -------------
+                   |   LOCAL   |
+                   -------------
+........................................
+
+Git options to use:
+~~~~~~~~~~~~~~~~~~~
+ - `branch.<branch>.remote`
+ - `branch.<branch>.pushRemote`
+ - `remote.pushDefault`
+ - `push.default`
+
+See linkgit:git-config[1].
+
+Push behaviour
+~~~~~~~~~~~~~~
+
+Setting the behavior of push for the triangular workflow:
+
+===========================
+* `git config push.default current`
+===========================
+
+
+Case 1: LOCAL is a clone of **PUBLIC-FORK**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+'In this case, the remote named `origin` corresponds to **PUBLIC-FORK**.'
+
+Adding **UPSTREAM** remote:
+
+===================================
+* `git remote add upstream <UPSTREAM_url>`
+===================================
+
+Setting `branch.<branch>.remote` and `branch.<branch>.pushRemote` in
+order to:
+
+ - pull from **UPSTREAM** without argument for pull
+ - push to **PUBLIC-FORK** (`origin`) without argument for push
+
+Example with master as <branch>:
+===================================
+* `git config branch.master.remote upstream`
+* `git config branch.master.pushRemote origin`
+===================================
+
+Case 2: LOCAL is a clone of **UPSTREAM**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+'In this case, the remote named `origin` corresponds to
+**UPSTREAM**.'
+
+Adding **PUBLIC-FORK** remote:
+
+===================================
+* `git remote add public_fork <PUBLIC-FORK_url>`
+===================================
+
+**Method 1: One option for all branches**
+
+Setting `remote.pushDefault` in order to push to **PUBLIC-FORK** without
+argument for push.
+
+===================================
+* `git config remote.pushDefault public_fork`
+===================================
+
+**Method 2: Each branch its option**
+
+Setting `branch.<branch>.pushRemote` in order to push to **PUBLIC-FORK**
+without argument to push.
+
+Example with master as <branch>:
+===================================
+* `git config branch.master.pushRemote public_fork`
+===================================
+
+
+Stay up-to-date
+~~~~~~~~~~~~~~~
+
+Retrieving updates from **UPSTREAM** with `git pull` and sending
+them to **PUBLIC-FORK** with `git push`.
+
+Checks
+~~~~~~
+
+Uses of command line shorthand `@{push}` and `@{upstream}`.
+
+**Display the push remote's name: **
+
+===================================
+* `git rev-parse --abbrev-ref '@{push}'`
+===================================
+
+The shorthand `<branch>@{push}` denotes the remote-tracking branch
+where the <branch> would be pushed to. If no <branch> is specified
+(`@{push}`), <branch> takes the value of the current branch.
+
+See linkgit:git-rev-parse[1].
+
+**Display the fetch remote's name: **
+
+===================================
+* `git rev-parse --abbrev-ref '@{upstream}'`
+===================================
+
+The shorthand "<branch>@{upstream}" substitutes the name of the
+"upstream" of the branch. If no <branch> is specified (`@{upstream}`),
+<branch> takes the value of the current branch.
+
+**Display commits added to the current branch since last push: **
+
+===============
+* `git log @{push}..`
+===============
+
+See linkgit:git-log[1].
+
+**Display commits added to a specific branch since last push: **
+
+==============================
+* `git log <branch_name>@{push}..`
+==============================
 
 SEE ALSO
 --------
@@ -474,6 +625,10 @@ linkgit:git-rebase[1],
 linkgit:git-format-patch[1],
 linkgit:git-send-email[1],
 linkgit:git-am[1]
+linkgit:git-config[1],
+linkgit:git-log[1],
+linkgit:git-rev-parse[1]
+
 
 GIT
 ---
-- 
2.7.4 (Apple Git-66)

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Philip Oakley]

From: "Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>
> Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:
>
>>> Matthieu Moy <matthieu.moy@grenoble-inp.fr> a écrit :
>>>
>>> That is technically correct, but to illustrate the overall flow, I'd
>>> rather avoid naming the repositories in terms of git commands. If you do
>>> so, you will probably end up with tautological explanations like this
>>> later in the text: "FETCH_REMOTE is the remote from where you fetch,
>>> PUSH_REMOTE is the remote to which you push, and LOCAL is local".
>>>
>>> I suggested PUBLIC-FORK earlier, and didn't get any feedback on it. I
>>> think it translates the intent better than PUSH_REMOTE. An alternative
>>> would be PUBLISH (= the repository you use to publish your changes so
>>> that the maintainer can pick them).
>>
>>> "Philip Oakley" <philipoakley@iee.org> writes:
>>> However your gitster/git repo feels like it would match the me/git
>>> viewpoint, in that while it is 'open', it isn't really a formal
>>> publishing place. Certainly I don't think that I 'publish' what's in
>>> my personal github repos, which I use as an open backup (and any
>>> PR's I put to the G4W project repo are referenced from there).
>>
>>
>> For Philip Oakley, PUBLISH seems to not be a good name.
>> For PUBLIC-FORK, a fork can be private so I think that’s not a good idea.
>
> I don't think you will find a name that fits all use-cases. IHMO, best
> is to pick one rather general use-case, make the explanations for it,
> and maybe explain somewhere that there are variants.
>
> If the fork is completely private, then your diagram with a "maintainer"
> arrow from it to upstream is not valid.

That's only true for a Pull Request workflow. For a Patch workflow (such as 
Git) the user's home vault can be completely private.

>  It needs at least to be visible
> to the maintainer. "public" may be a bit strong as you don't need to
> make it "public" to everyone on earth, but to me that's OK to describe
> the use-case.
>
>> As the third-place is the repository used to work on commits/patches,
>> a simple name can be WORK_REPOSITORY.
>
> "WORK" is already used to describe "worktree" which is precisely not
> this repository. I don't "work" on my public fork, I "work" locally and
> then just send commits there.
>
> -- 
> Matthieu Moy
> http://www-verimag.imag.fr/~moy/
> --
> 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
> 

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Matthieu Moy]

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

> From: "Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>
>>
>> I don't think you will find a name that fits all use-cases. IHMO, best
>> is to pick one rather general use-case, make the explanations for it,
>> and maybe explain somewhere that there are variants.
>>
>> If the fork is completely private, then your diagram with a "maintainer"
>> arrow from it to upstream is not valid.
>
> That's only true for a Pull Request workflow. For a Patch workflow
> (such as Git) the user's home vault can be completely private.

But then the maintainer is not the one picking changes from it (you're
sending them by email), so the "maintainer" label is not really accurate
in the diagram:

+------------               -----------
+| UPSTREAM |  maintainer   | ORIGIN  |
+|  git/git |- - - - - - - -|  me/git |
+------------       ←       -----------
+         \                   /
+          \                 /
+     fetch↓\               /↑push
+            \             /
+             \           /
+             -------------
+             |   LOCAL   |
+             -------------

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Philip Oakley]

From: "Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> From: "Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>
>>>
>>> I don't think you will find a name that fits all use-cases. IHMO, best
>>> is to pick one rather general use-case, make the explanations for it,
>>> and maybe explain somewhere that there are variants.
>>>
>>> If the fork is completely private, then your diagram with a "maintainer"
>>> arrow from it to upstream is not valid.
>>
>> That's only true for a Pull Request workflow. For a Patch workflow
>> (such as Git) the user's home vault can be completely private.
>
> But then the maintainer is not the one picking changes from it (you're
> sending them by email), so the "maintainer" label is not really accurate
> in the diagram:
>
> +------------               -----------
> +| UPSTREAM |  maintainer   | ORIGIN  |
> +|  git/git |- - - - - - - -|  me/git |
> +------------       ←       -----------
> +         \                   /
> +          \                 /
> +     fetch↓\               /↑push
> +            \             /
> +             \           /
> +             -------------
> +             |   LOCAL   |
> +             -------------
>
Ahh, that's a useful clarification. I use my git repo both for the G4W 
(which does take pull requests) and for Junio's Git.

The use of the 'home-vault' fork as being for
(a) backup,
(b) open viewing, and
(c) sending pull requests
are subtle distinctions for the naming (of both the forked repo, and the 
workflow).

It's probably even worse in a corporate environment as to how personal the 
personal home vault is, as compared to just having a namespace in a 
centralised dev server/repo. (the question of how to make such arrangements 
seems to come up moderately often on the various lists)

Philip 

Re: [RFC/PATCHv2] Documentation: triangular workflow

[Junio C Hamano]

Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:

> +TRIANGULAR WORKFLOW
> +-------------------
> +
> +In some projects, you cannot push directly to the project but have to
> +suggest your commits to the maintainer (e.g. pull requests).
> +For these projects, it's common to use what's called a *triangular
> +workflow*:
> +
> +- Taking the last version of the project by fetching (e.g.
> +  **UPSTREAM**)
> +- Writing modifications and push them to a fork (e.g. **PUBLIC-FORK**)
> +- Opening a pull request
> +- Checking of changes by the maintainer and, merging them into the
> +  **UPSTREAM** repository if accepted
> +
> +
> +........................................
> +------------------               -----------------
> +| UPSTREAM       |  maintainer   | PUBLIC-FORK   |
> +|  git/git       |- - - - - - - -|  me/remote    |
> +------------------       ←       -----------------
> +              \                     /
> +               \                   /
> +          fetch↓\                 /↑push
> +                 \               /
> +                  \             /
> +                   -------------
> +                   |   LOCAL   |
> +                   -------------
> +........................................

I agree with other commenters that "PUBLIC-FORK" is a name that does
not capture the essense of the triangular being the next step
forward, compared to the "central shared repository" workflow, to
take advantage of the distributed nature of Git.

"Where you push so that somebody else can fetch from there" does not
have to be public.  You may be submitting a course assignment there,
only to be seen by your professor but not by others in the class.
Also, you do not your call "LOCAL" a "LOCAL-FORK" and that is a good
thing.  In a distributed world, everything is a fork, so adding
"-FORK" to a name is pretty much meaningless.

So neither "PUBLIC" nor "FORK" in "PUBLIC-FORK" is a good word to
describe this thing.

The only reason you are pushing there is because your "LOCAL" is
either not accessible from outside world, and/or you do not want to
give a direct access to it (otherwise you could have allowed an
access to whoever is going to fetch from you direct access to
"LOCAL" and be done with it without creating "PUBLIC-FORK").

That is why I reminded that we earlier in the design phase called
this "publish"; it is a place you give access to others a selected
work of yours that you choose to give them access to.  Whether you
are a leaf contributor, a student who got stuck and wants to ask
suggestions from your friends after looking your code over, or an
integrator of a big public project, I would view the act to push
into such a place you give selective visibility to your work to
others as publishing your work.

Re: [RFC/PATCHv2] Documentation: triangular workflow

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:
>
>> +TRIANGULAR WORKFLOW
>> +-------------------
>> +
>> +In some projects, you cannot push directly to the project but have to
>> +suggest your commits to the maintainer (e.g. pull requests).
>> +For these projects, it's common to use what's called a *triangular
>> +workflow*:
>> +
>> +- Taking the last version of the project by fetching (e.g.
>> +  **UPSTREAM**)
>> +- Writing modifications and push them to a fork (e.g. **PUBLIC-FORK**)
>> +- Opening a pull request
>> +- Checking of changes by the maintainer and, merging them into the
>> +  **UPSTREAM** repository if accepted
>> +
>> +
>> +........................................
>> +------------------               -----------------
>> +| UPSTREAM       |  maintainer   | PUBLIC-FORK   |
>> +|  git/git       |- - - - - - - -|  me/remote    |
>> +------------------       ←       -----------------
>> +              \                     /
>> +               \                   /
>> +          fetch↓\                 /↑push
>> +                 \               /
>> +                  \             /
>> +                   -------------
>> +                   |   LOCAL   |
>> +                   -------------
>> +........................................
>
> I agree with other commenters that "PUBLIC-FORK" is a name that does
> not capture the essense of the triangular being the next step
> forward, compared to the "central shared repository" workflow, to
> take advantage of the distributed nature of Git.
>
> "Where you push so that somebody else can fetch from there" does not
> have to be public.  You may be submitting a course assignment there,
> only to be seen by your professor but not by others in the class.
> Also, you do not your call "LOCAL" a "LOCAL-FORK" and that is a good
> thing.  In a distributed world, everything is a fork, so adding
> "-FORK" to a name is pretty much meaningless.
>
> So neither "PUBLIC" nor "FORK" in "PUBLIC-FORK" is a good word to
> describe this thing.
>
> The only reason you are pushing there is because your "LOCAL" is
> either not accessible from outside world, and/or you do not want to
> give a direct access to it (otherwise you could have allowed an
> access to whoever is going to fetch from you direct access to
> "LOCAL" and be done with it without creating "PUBLIC-FORK").
>
> That is why I reminded that we earlier in the design phase called
> this "publish"; it is a place you give access to others a selected
> work of yours that you choose to give them access to.

Given that clarification I'd be happier to go with it being one's 'Publish' 
repo.

My initial reticence was because of the association of "publish" with vanity 
publishing and other forms of over-sharing and self promotion.

A clarification/explanation that calling it a 'publish' repo is about 
granting access, and possible open access, would make it more acceptable.

> Whether you
> are a leaf contributor, a student who got stuck and wants to ask
> suggestions from your friends after looking your code over, or an
> integrator of a big public project, I would view the act to push
> into such a place you give selective visibility to your work to
> others as publishing your work.

Agreed, in that context.

--
Philip 

Re: [RFC/PATCHv2] Documentation: triangular workflow

[Matthieu Moy]

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

> Given that clarification I'd be happier to go with it being one's
> 'Publish' repo.
>
> My initial reticence was because of the association of "publish" with
> vanity publishing and other forms of over-sharing and self promotion.
>
> A clarification/explanation that calling it a 'publish' repo is about
> granting access, and possible open access, would make it more
> acceptable.

I think "publish" is the best we found up to now.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Matthieu Moy]

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

> From: "Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>
>
>> But then the maintainer is not the one picking changes from it (you're
>> sending them by email), so the "maintainer" label is not really accurate
>> in the diagram:
>>
>> +------------               -----------
>> +| UPSTREAM |  maintainer   | ORIGIN  |
>> +|  git/git |- - - - - - - -|  me/git |
>> +------------       ←       -----------
>> +         \                   /
>> +          \                 /
>> +     fetch↓\               /↑push
>> +            \             /
>> +             \           /
>> +             -------------
>> +             |   LOCAL   |
>> +             -------------
>>
> Ahh, that's a useful clarification. I use my git repo both for the G4W
> (which does take pull requests) and for Junio's Git.
>
> The use of the 'home-vault' fork as being for
> (a) backup,
> (b) open viewing, and
> (c) sending pull requests
> are subtle distinctions for the naming (of both the forked repo, and
> the workflow).
>
> It's probably even worse in a corporate environment as to how personal
> the personal home vault is, as compared to just having a namespace in
> a centralised dev server/repo. (the question of how to make such
> arrangements seems to come up moderately often on the various lists)

Yes, but again, the point of this thread is to document *one* workflow,
not all possible uses of pushRemote. It's much easier to describe "one
typical triangular workflow" in a concrete way than to try to be
completely general and end up with a description that average users
would just not understand.

It would be different to me if we were writting the pushRemote part of
config.txt, where we have to be as general as possible.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [RFC/PATCHv2] Documentation: triangular workflow

[Jordan DE GEA]

> Le 7 juin 2016 à 08:58, Matthieu Moy <matthieu.moy@grenoble-inp.fr> a écrit :
> 
> "Philip Oakley" <philipoakley@iee.org> writes:
> 
>> Given that clarification I'd be happier to go with it being one's
>> 'Publish' repo.
>> 
>> My initial reticence was because of the association of "publish" with
>> vanity publishing and other forms of over-sharing and self promotion.
>> 
>> A clarification/explanation that calling it a 'publish' repo is about
>> granting access, and possible open access, would make it more
>> acceptable.
> 
> I think "publish" is the best we found up to now.
> 

It seems that we choose ‘publish’. 
I’ll send the v3 of the patch soon. 

[PATCHv3] Documentation: triangular workflow

[Jordan DE GEA]

Currently, triangular workflow can be configured, but there is no
documentation about it. A documentation is useful to keep
configuration possibilities up-to-date.

A new subsection is created in gitworkflow.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
Signed-off-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
---
Changes since version 2:
 - PUBLIC-FORK renamed for PUBLISH

Changes since version 1:
 - content moved in gitworktree
 - content improved

 Documentation/gitworkflows.txt | 154 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 154 insertions(+)

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index f16c414..3b5fd09 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -463,6 +463,156 @@ if you get conflicts: `git am -3` will use index information contained
 in patches to figure out the merge base.  See linkgit:git-am[1] for
 other options.
 
+TRIANGULAR WORKFLOW
+-------------------
+
+In some projects, you cannot push directly to the project but have to
+suggest your commits to the maintainer (e.g. pull requests).
+For these projects, it's common to use what's called a *triangular
+workflow*:
+
+- Taking the last version of the project by fetching (e.g.
+  **UPSTREAM**)
+- Writing modifications and push them to a fork (e.g. **PUBLISH**)
+- Opening a pull request
+- Checking of changes by the maintainer and, merging them into the
+  **UPSTREAM** repository if accepted
+
+
+........................................
+------------------               -----------------
+| UPSTREAM       |  maintainer   | PUBLISH       |
+|  git/git       |- - - - - - - -|  me/remote    |
+------------------       ←       -----------------
+              \                     /
+               \                   /
+          fetch↓\                 /↑push
+                 \               /
+                  \             /
+                   -------------
+                   |   LOCAL   |
+                   -------------
+........................................
+
+Git options to use:
+~~~~~~~~~~~~~~~~~~~
+ - `branch.<branch>.remote`
+ - `branch.<branch>.pushRemote`
+ - `remote.pushDefault`
+ - `push.default`
+
+See linkgit:git-config[1].
+
+Push behaviour
+~~~~~~~~~~~~~~
+
+Setting the behavior of push for the triangular workflow:
+
+===========================
+* `git config push.default current`
+===========================
+
+
+Case 1: LOCAL is a clone of **PUBLISH**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+'In this case, the remote named `origin` corresponds to **PUBLISH**.'
+
+Adding **UPSTREAM** remote:
+
+===================================
+* `git remote add upstream <UPSTREAM_url>`
+===================================
+
+Setting `branch.<branch>.remote` and `branch.<branch>.pushRemote` in
+order to:
+
+ - pull from **UPSTREAM** without argument for pull
+ - push to **PUBLISH** (`origin`) without argument for push
+
+Example with master as <branch>:
+===================================
+* `git config branch.master.remote upstream`
+* `git config branch.master.pushRemote origin`
+===================================
+
+Case 2: LOCAL is a clone of **UPSTREAM**
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+'In this case, the remote named `origin` corresponds to **UPSTREAM**.'
+
+Adding **PUBLISH** remote:
+
+===================================
+* `git remote add publish <PUBLISH_url>`
+===================================
+
+**Method 1: One option for all branches**
+
+Setting `remote.pushDefault` in order to push to **PUBLISH** without
+argument for push.
+
+===================================
+* `git config remote.pushDefault publish`
+===================================
+
+**Method 2: Each branch its option**
+
+Setting `branch.<branch>.pushRemote` in order to push to **PUBLISH**
+without argument to push.
+
+Example with master as <branch>:
+===================================
+* `git config branch.master.pushRemote publish`
+===================================
+
+
+Stay up-to-date
+~~~~~~~~~~~~~~~
+
+Retrieving updates from **UPSTREAM** with `git pull` and sending
+them to **PUBLISH** with `git push`.
+
+Checks
+~~~~~~
+
+Uses of command line shorthand `@{push}` and `@{upstream}`.
+
+**Display the push remote's name: **
+
+===================================
+* `git rev-parse --abbrev-ref '@{push}'`
+===================================
+
+The shorthand `<branch>@{push}` denotes the remote-tracking branch
+where the <branch> would be pushed to. If no <branch> is specified
+(`@{push}`), <branch> takes the value of the current branch.
+
+See linkgit:git-rev-parse[1].
+
+**Display the fetch remote's name: **
+
+===================================
+* `git rev-parse --abbrev-ref '@{upstream}'`
+===================================
+
+The shorthand "<branch>@{upstream}" substitutes the name of the
+"upstream" of the branch. If no <branch> is specified (`@{upstream}`),
+<branch> takes the value of the current branch.
+
+**Display commits added to the current branch since last push: **
+
+===============
+* `git log @{push}..`
+===============
+
+See linkgit:git-log[1].
+
+**Display commits added to a specific branch since last push: **
+
+==============================
+* `git log <branch_name>@{push}..`
+==============================
 
 SEE ALSO
 --------
@@ -474,6 +624,10 @@ linkgit:git-rebase[1],
 linkgit:git-format-patch[1],
 linkgit:git-send-email[1],
 linkgit:git-am[1]
+linkgit:git-config[1],
+linkgit:git-log[1],
+linkgit:git-rev-parse[1]
+
 
 GIT
 ---
-- 
2.7.4 (Apple Git-66)

Re: [PATCHv3] Documentation: triangular workflow

[Junio C Hamano]

Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:

> diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
> index f16c414..3b5fd09 100644
> --- a/Documentation/gitworkflows.txt
> +++ b/Documentation/gitworkflows.txt
> @@ -463,6 +463,156 @@ if you get conflicts: `git am -3` will use index information contained
>  in patches to figure out the merge base.  See linkgit:git-am[1] for
>  other options.
>  
> +TRIANGULAR WORKFLOW
> +-------------------
> +
> +In some projects, you cannot push directly to the project but have to
> +suggest your commits to the maintainer (e.g. pull requests).
> +For these projects, it's common to use what's called a *triangular
> +workflow*:
> +
> +- Taking the last version of the project by fetching (e.g.
> +  **UPSTREAM**)

"by fetching (e.g. UPSTREAM)" does not finish the sentence nicely.

"... by fetching from **UPSTREAM**" would work better.  So would
"Fetching the latest version from the project (e.g. UPSTREAM)".

> +- Writing modifications and push them to a fork (e.g. **PUBLISH**)
> +- Opening a pull request
> +- Checking of changes by the maintainer and, merging them into the
> +  **UPSTREAM** repository if accepted

You'd want to end these sentences with full-stop, by the way

> +........................................
> +------------------               -----------------
> +| UPSTREAM       |  maintainer   | PUBLISH       |
> +|  git/git       |- - - - - - - -|  me/remote    |
> +------------------       ←       -----------------
> +              \                     /
> +               \                   /
> +          fetch↓\                 /↑push
> +                 \               /
> +                  \             /
> +                   -------------
> +                   |   LOCAL   |
> +                   -------------
> +........................................
> +
> +Git options to use:
> +~~~~~~~~~~~~~~~~~~~
> + - `branch.<branch>.remote`
> + - `branch.<branch>.pushRemote`
> + - `remote.pushDefault`
> + - `push.default`
> +
> +See linkgit:git-config[1].

The title says "options" but listed are configuration variables and
the referred document is also about git-config.  Perhaps retitle it to

	Useful configuration variables
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

or something like that?

One thing after reading the above lines that immediately came to my
mind was this:

    After listing these four and telling the reader to "See ...", is
    there anything else the reader needs to learn from below?

It may make the result a lot more useful document if this gives an
impression to the reader as if you are saying (you do not have to
actually say it) "We will guide you how to set up your workflow in
triangular way, and here are the key configuration variables you
will end up using; don't worry about the details of them, we'll
teach you all about them soon in the following paragraphs."

And I found that "See linkgit:git-config[1]" go directly against
that line of narrative.

> +Push behaviour
> +~~~~~~~~~~~~~~
> + ...
> +
> +Case 2: LOCAL is a clone of **UPSTREAM**
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +'In this case, the remote named `origin` corresponds to **UPSTREAM**.'
> +
> +Adding **PUBLISH** remote:
> +
> +===================================
> +* `git remote add publish <PUBLISH_url>`
> +===================================

It may perhaps be only me, but these blind instructions puts me off,
and what I find lacking is "Why should I do this?"  "What benefit do
I get by doing this".  Start it perhaps like this?

	Because you will be pushing into the publish repository
	often, instead of having to type its URL every time, you
	want a short name you can use to call it.

and then give that "remote add".

> +
> +**Method 1: One option for all branches**
> +
> +Setting `remote.pushDefault` in order to push to **PUBLISH** without
> +argument for push.
> +
> +===================================
> +* `git config remote.pushDefault publish`
> +===================================

This is not too bad, but I'd say

	With the "remote add" above, you can say "git push publish"
	to push there, instead of saying its URL.  But you may want
	to be even lazier and say just "git push".  To do so:

As a document that is geared toward being a tutorial, I personally
think it is better to stick to one arrangement rather than
presenting case 1/2 as two equivalently valid arrangements and
describe them to equal degree of detail.  Otherwise, after finishing
reading Case 1 and immediately reading Case 2 heading, the reader
would start wondering "Which one should I pick?  What are the pros
and cons?".

A typical reader of this document would have an upstream in mind,
perhaps a clone of it locally, and may or may not yet have a publish
repository, so one valid choice could be to use Case 2.

Whichever one you choose, the description should not begin with
"pushing".  A reader who is the target of this document (i.e. who
owns the LOCAL and PUBLISH repository) begins by cloning and/or
fetching, followed by working on her own change while staying up to
date, and pushing is the last thing she does in the flow.

So I'd recommend reordering the description to

    * Introduction.  As a summary, here are the four configuration
      variables you'll be using to make it easier to arrange.

    * "Preparation".  Clone from the upstream, create an empty
      publish repository and set it as a secondary remote, with
      pushdefault pointing at it.

    * "Staying up-to-date".  You do not have to describe "git fetch"
      or "git pull" from the upstream aka origin with too much
      detail, as having or not having a publish repository does not
      change anything on this side.

    * "Making your work available".  You would want to reiterate the
      fact that "git push" does not go to the upstream but to your
      publishing place thanks to the earlier pushdefault
      configuration.

    * "Alternatively...".  In this section, you could mention
      possible other arrangements.  One could be to set pushdefault
      for each and every branch (aka your Case 2/Method 2), which
      shouldn't be necesssary because at the beginning of the
      document we made it clear that we assume that the reader
      cannot push to upstream--the normal place she would be pushing
      is to her own publishing place, and configuring "usually all
      of them go to my publishing place, but this one alone will go
      someplace else" (1) is an advanced workflow element, and more
      importantly (2) is not specific to triangular workflow.

      Another altenative arrangement worth mentioning may be your
      Case 1, i.e. to point at your publish place and a secondary
      "upstream" pointing at where your upstream publishes their
      work.  You can describe what needs to be changed compared to
      the above three sections.

so that a first-time reader can learn _one_ workable organization
quickly without having to choose blindly between many choices.

Thanks.

Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation

[Philip Oakley]

From: "Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>> From: "Matthieu Moy" <Matthieu.Moy@grenoble-inp.fr>
>>
>>> But then the maintainer is not the one picking changes from it (you're
>>> sending them by email), so the "maintainer" label is not really accurate
>>> in the diagram:
>>>
>>> +------------               -----------
>>> +| UPSTREAM |  maintainer   | ORIGIN  |
>>> +|  git/git |- - - - - - - -|  me/git |
>>> +------------       ←       -----------
>>> +         \                   /
>>> +          \                 /
>>> +     fetch↓\               /↑push
>>> +            \             /
>>> +             \           /
>>> +             -------------
>>> +             |   LOCAL   |
>>> +             -------------
>>>
>> Ahh, that's a useful clarification. I use my git repo both for the G4W
>> (which does take pull requests) and for Junio's Git.
>>
>> The use of the 'home-vault' fork as being for
>> (a) backup,
>> (b) open viewing, and
>> (c) sending pull requests
>> are subtle distinctions for the naming (of both the forked repo, and
>> the workflow).
>>
>> It's probably even worse in a corporate environment as to how personal
>> the personal home vault is, as compared to just having a namespace in
>> a centralised dev server/repo. (the question of how to make such
>> arrangements seems to come up moderately often on the various lists)
>
> Yes, but again, the point of this thread is to document *one* workflow,

I'd agree here.

> not all possible uses of pushRemote. It's much easier to describe "one
> typical triangular workflow" in a concrete way

That *one* workflow would be a _specific_ flow - I'm reading 'typical' as
implying common/general workflow(s), which may not be what you hoped to
convey.

>   than to try to be
> completely general and end up with a description that average users
> would just not understand.

I do think that the description of the one specific flow should include the
clarifications that discriminate it from other, potentially mistakenly
confused with this one, flows. It would be that disambiguation that would
clear up the misunderstanding.

>
> It would be different to me if we were writting the pushRemote part of
> config.txt, where we have to be as general as possible.

As an aside, the discussion has indicated that the documentation may be a
bit light on describing (and referencing) how multi-user server set-ups can
be arranged to faciltate (or may hinder) the different flows.
--
Philip
(mail delayed by lack of wifi) 

Re: [PATCHv3] Documentation: triangular workflow

[Jordan DE GEA]

> Le 7 juin 2016 à 21:12, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:
> 
>> +
>> +- Taking the last version of the project by fetching (e.g.
>> +  **UPSTREAM**)
> 
> "by fetching (e.g. UPSTREAM)" does not finish the sentence nicely.
> 
> "... by fetching from **UPSTREAM**" would work better.  So would
> "Fetching the latest version from the project (e.g. UPSTREAM) ».

Ok. Changed for the next iteration. 

>> +- Writing modifications and push them to a fork (e.g. **PUBLISH**)
>> +- Opening a pull request
>> +- Checking of changes by the maintainer and, merging them into the
>> +  **UPSTREAM** repository if accepted
> 
> You'd want to end these sentences with full-stop, by the way
> 

OK too. 

>> +........................................
>> +------------------               -----------------
>> +| UPSTREAM       |  maintainer   | PUBLISH       |
>> +|  git/git       |- - - - - - - -|  me/remote    |
>> +------------------       ←       -----------------
>> +              \                     /
>> +               \                   /
>> +          fetch↓\                 /↑push
>> +                 \               /
>> +                  \             /
>> +                   -------------
>> +                   |   LOCAL   |
>> +                   -------------
>> +........................................
>> +
>> +Git options to use:
>> +~~~~~~~~~~~~~~~~~~~
>> + - `branch.<branch>.remote`
>> + - `branch.<branch>.pushRemote`
>> + - `remote.pushDefault`
>> + - `push.default`
>> +
>> +See linkgit:git-config[1].
> 
> The title says "options" but listed are configuration variables and
> the referred document is also about git-config.  Perhaps retitle it to
> 
> 	Useful configuration variables
>        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> 

Ok too. 


> or something like that?
> 
> One thing after reading the above lines that immediately came to my
> mind was this:
> 
>    After listing these four and telling the reader to "See ...", is
>    there anything else the reader needs to learn from below?
> 
> It may make the result a lot more useful document if this gives an
> impression to the reader as if you are saying (you do not have to
> actually say it) "We will guide you how to set up your workflow in
> triangular way, and here are the key configuration variables you
> will end up using; don't worry about the details of them, we'll
> teach you all about them soon in the following paragraphs."
> 
> And I found that "See linkgit:git-config[1]" go directly against
> that line of narrative.

A link is already added at the end of the document. So I delete this one. 

> 
>> +Push behaviour
>> +~~~~~~~~~~~~~~
>> + ...
>> +
>> +Case 2: LOCAL is a clone of **UPSTREAM**
>> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
>> +
>> +'In this case, the remote named `origin` corresponds to **UPSTREAM**.'
>> +
>> +Adding **PUBLISH** remote:
>> +
>> +===================================
>> +* `git remote add publish <PUBLISH_url>`
>> +===================================
> 
> It may perhaps be only me, but these blind instructions puts me off,
> and what I find lacking is "Why should I do this?"  "What benefit do
> I get by doing this".  Start it perhaps like this?
> 
> 	Because you will be pushing into the publish repository
> 	often, instead of having to type its URL every time, you
> 	want a short name you can use to call it.
> 
> and then give that "remote add".

Ok. Similar text added for the next iteration. 

>> +
>> +**Method 1: One option for all branches**
>> +
>> +Setting `remote.pushDefault` in order to push to **PUBLISH** without
>> +argument for push.
>> +
>> +===================================
>> +* `git config remote.pushDefault publish`
>> +===================================
> 
> This is not too bad, but I'd say
> 
> 	With the "remote add" above, you can say "git push publish"
> 	to push there, instead of saying its URL.  But you may want
> 	to be even lazier and say just "git push".  To do so:
> 

Ok too. Similar text added for the next iteration. 

> As a document that is geared toward being a tutorial, I personally
> think it is better to stick to one arrangement rather than
> presenting case 1/2 as two equivalently valid arrangements and
> describe them to equal degree of detail.  Otherwise, after finishing
> reading Case 1 and immediately reading Case 2 heading, the reader
> would start wondering "Which one should I pick?  What are the pros
> and cons?".
> 
> A typical reader of this document would have an upstream in mind,
> perhaps a clone of it locally, and may or may not yet have a publish
> repository, so one valid choice could be to use Case 2.
> 
> Whichever one you choose, the description should not begin with
> "pushing".  A reader who is the target of this document (i.e. who
> owns the LOCAL and PUBLISH repository) begins by cloning and/or
> fetching, followed by working on her own change while staying up to
> date, and pushing is the last thing she does in the flow.
> 
> So I'd recommend reordering the description to
> 
>    * Introduction.  As a summary, here are the four configuration
>      variables you'll be using to make it easier to arrange.
> 
>    * "Preparation".  Clone from the upstream, create an empty
>      publish repository and set it as a secondary remote, with
>      pushdefault pointing at it.
> 
>    * "Staying up-to-date".  You do not have to describe "git fetch"
>      or "git pull" from the upstream aka origin with too much
>      detail, as having or not having a publish repository does not
>      change anything on this side.
> 
>    * "Making your work available".  You would want to reiterate the
>      fact that "git push" does not go to the upstream but to your
>      publishing place thanks to the earlier pushdefault
>      configuration.
> 
>    * "Alternatively...".  In this section, you could mention
>      possible other arrangements.  One could be to set pushdefault
>      for each and every branch (aka your Case 2/Method 2), which
>      shouldn't be necesssary because at the beginning of the
>      document we made it clear that we assume that the reader
>      cannot push to upstream--the normal place she would be pushing
>      is to her own publishing place, and configuring "usually all
>      of them go to my publishing place, but this one alone will go
>      someplace else" (1) is an advanced workflow element, and more
>      importantly (2) is not specific to triangular workflow.
> 
>      Another altenative arrangement worth mentioning may be your
>      Case 1, i.e. to point at your publish place and a secondary
>      "upstream" pointing at where your upstream publishes their
>      work.  You can describe what needs to be changed compared to
>      the above three sections.

Yes, that clearer like that. I reorganize and send a new patch. 

Re: [PATCHv3] Documentation: triangular workflow

[Matthieu Moy]

Junio C Hamano <gitster@pobox.com> writes:

>     * Introduction.  As a summary, here are the four configuration
>       variables you'll be using to make it easier to arrange.

I'd actually skip this, and keep configuration variable names for later.
The very point of these --set-upstream & friends options is to allow the
user to work without knowing about them. Typically:

git clone http://example.com/foo
cd foo
# hack hack hack
git commit
git push

=> no configuration variable involved for the user, and it just works.

So, instead of having a flow like "We need to configure
branch.<branch>.merge, and a shortcut to do so is to use
--set-upstream", I'd rather see "Let's push and ask push to remember
where we're pushing so that we don't have to tell it again next time:
git push --set-upstream origin master. Oh, BTW, internally this sets
branch.<branch>.merge.".

Talking about --set-upstream, it does not appear at all in your
patch. Is this on purpose?


OTOH, an introduction that would motivate the workflow would be very
useful IMHO. I see many people using triangular workflows just because
"it's cool" and I can't be satisfied with this. Among real arguments:

* Allows contributor to work with Git even though they do not have write
  access to upstream.

* Symmetrically, this allows maintainers to receive code from
  contributors they don't trust a priori.

* This makes code review more efficient

* This encourrages clean history (because you can "rebase -i" and
  force-push as much as you want to your public fork before the code is
  merged)

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

[PATCHv4] Documentation: triangular workflow

[Jordan DE GEA]

Currently, triangular workflow can be configured, but there is no
documentation about it. A documentation is useful to keep
configuration possibilities up-to-date.

A new subsection is created in gitworkflow.

Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
Signed-off-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
Signed-off-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
---
Changes since v3:
 * Text reorganized to follow:
   - Introduction
   - Preparation
   - Staying up-to-date
   - Alternatively
 * Texts added to explain why we use commands in:
   - Preparation
   - Alternatively

 Documentation/gitworkflows.txt | 177 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 176 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitworkflows.txt b/Documentation/gitworkflows.txt
index f16c414..1ec1f63 100644
--- a/Documentation/gitworkflows.txt
+++ b/Documentation/gitworkflows.txt
@@ -463,6 +463,178 @@ if you get conflicts: `git am -3` will use index information contained
 in patches to figure out the merge base.  See linkgit:git-am[1] for
 other options.
 
+TRIANGULAR WORKFLOW
+-------------------
+
+In some projects, you cannot push directly to the project but have to
+suggest your commits to the maintainer (e.g. pull requests).
+For these projects, it's common to use what's called a *triangular
+workflow*:
+
+- Taking the last version of the project by fetching from **UPSTREAM**
+- Writing modifications and push them to a fork (e.g. **PUBLISH**)
+- Opening a pull request
+- If the maintainer accepts the changes, he merges them into the
+  **UPSTREAM** repository.
+
+
+........................................
+------------------               -----------------
+| UPSTREAM       |  maintainer   | PUBLISH       |
+|  git/git       |- - - - - - - -|  me/remote    |
+------------------       ←       -----------------
+              \                     /
+               \                   /
+          fetch↓\                 /↑push
+                 \               /
+                  \             /
+                   -------------
+                   |   LOCAL   |
+                   -------------
+........................................
+
+Motivations
+~~~~~~~~~~~
+
+* Allows contributors to work with Git even though they do not have
+write access to **UPSTREAM**.
+
+* Allows maintainers to receive code from contributors they may not
+trust.
+
+* Code review is more efficient
+
+* Encourages clean history by using `rebase -i` and `push --force` to 
+your public fork before the code is merged
+
+Preparation
+~~~~~~~~~~~
+
+Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty
+repository.
+
+======================
+`git clone <PUBLISH_url>`
+======================
+
+Setting the behavior of push for the triangular workflow:
+
+===========================
+`git config push.default current`
+===========================
+
+Adding **UPSTREAM** remote:
+
+===================================
+`git remote add upstream <UPSTREAM_url>`
+===================================
+
+With the `remote add` above, using `git pull upstream` pulls there,
+instead of saying its URL. In addition, `git pull` can pull from
+**UPSTREAM** without argument.
+
+For each branch requiring a triangular workflow, set
+`branch.<branch>.remote` and `branch.<branch>.pushRemote`.
+
+Example with master as <branch>:
+===================================
+* `git config branch.master.remote upstream`
+* `git config branch.master.pushRemote origin`
+===================================
+
+Stay up-to-date
+~~~~~~~~~~~~~~~
+
+Retrieve updates from **UPSTREAM** with `git pull` and send them to
+**PUBLISH** with `git push`.
+
+Checks
+~~~~~~
+
+.Display the push remote's name:
+[caption="Recipe: "]
+
+=================================
+`git rev-parse --abbrev-ref @{push}`
+=================================
+
+The shorthand `<branch>@{push}` denotes the remote-tracking branch
+where the <branch> would be pushed to. If no <branch> is specified
+(`@{push}`), <branch> takes the value of the current branch.
+
+
+.Display the fetch remote's name:
+[caption="Recipe: "]
+
+===================================
+`git rev-parse --abbrev-ref @{upstream}`
+===================================
+
+The shorthand `<branch>@{upstream}` substitutes the upstream name of
+the branch. If no <branch> is specified (`@{upstream}`), <branch>
+takes the value of the current branch.
+
+.Display commits added to the current branch since last push:
+[caption="Recipe: "]
+
+===============
+`git log @{push}..`
+===============
+
+.Display commits added to a specific branch since last push:
+[caption="Recipe: "]
+
+============================
+`git log <branch_name>@{push}..`
+============================
+
+Alternative configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.Cloning from **UPSTREAM**
+[caption="Recipe: "]
+
+In the preparation above, a clone from **PUBLISH** was used. Starting
+with a clone of **UPSTREAM** is possible too.
+
+Cloning from **UPSTREAM**
+
+======================
+`git clone <UPSTREAM_url>`
+======================
+
+Setting the behavior of push for the triangular workflow:
+
+===========================
+`git config push.default current`
+===========================
+
+Because modifications will be often pushed into the **PUBLISH** repository,
+instead of having to type its URL every time, a short name can be used
+to call it.
+
+Adding **PUBLISH** remote:
+
+===================================
+`git remote add publish <PUBLISH_url>`
+===================================
+
+With the `remote add` above, using `git push publish` pushes there,
+instead of saying its URL. In addition, `git push` can push to
+**PUBLISH** without argument.
+
+'Method 1: One option for all branches'
+
+===================================
+`git config remote.pushDefault publish`
+===================================
+
+'Method 2: Each branch its option'
+
+Example with master as <branch>:
+===================================
+`git config branch.master.pushRemote publish`
+===================================
 
 SEE ALSO
 --------
@@ -473,7 +645,10 @@ linkgit:git-merge[1],
 linkgit:git-rebase[1],
 linkgit:git-format-patch[1],
 linkgit:git-send-email[1],
-linkgit:git-am[1]
+linkgit:git-am[1],
+linkgit:git-config[1],
+linkgit:git-log[1],
+linkgit:git-rev-parse[1]
 
 GIT
 ---
-- 
2.7.4 (Apple Git-66)

Re: [PATCHv4] Documentation: triangular workflow

[Junio C Hamano]

Jordan DE GEA <jordan.de-gea@grenoble-inp.org> writes:

> +Motivations
> +~~~~~~~~~~~

> +* Allows contributors to work with Git even though they do not have
> +write access to **UPSTREAM**.
>
> +* Allows maintainers to receive code from contributors they may not
> +trust.

I somehow don't think "even though" sits well here.  You can work
with Git all you want locally even if you do not have write access
anywhere, but that is stating the obvious.  Also, unless the only
alternative you are contrasting "triangular" with is "a single
central repository workflow", "may not trust" is not a unique
advantage of "triangular".  You can exchange patches and reviews
with contributors just like you do.

I think the more important thing to say instead of the above two is
that this arrangement allows distributed workflow; you publish to
your place at your own pace, they pull from you if and when they
choose to, and they publish their result to their place at their own
pace.

> +* Code review is more efficient

I have no idea what data you have to back this claim up.  More
efficient compared to what?

If you are contrasting "triangular" with "a single central
repository everybody pushes into", then one big advantage
"triangular" can have around "code review" is that it allows reviews
before the code hits the authoritative history of the project.  If
your project works with a single central repository everybody pushes
into, things tend to run in reverse--after you push questionable
stuff into the project history, somebody else has to spot problems,
go in and fix it after the fact.

> +* Encourages clean history by using `rebase -i` and `push --force` to 
> +your public fork before the code is merged

This is a side-effect of "review before merge" mentioned earlier.


> +Preparation
> +~~~~~~~~~~~
> +
> +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty
> +repository.
> +
> +======================
> +`git clone <PUBLISH_url>`
> +======================
> +
> +Setting the behavior of push for the triangular workflow:
> +
> +===========================
> +`git config push.default current`
> +===========================
> +
> +Adding **UPSTREAM** remote:
> +
> +===================================
> +`git remote add upstream <UPSTREAM_url>`
> +===================================
> +
> +With the `remote add` above, using `git pull upstream` pulls there,
> +instead of saying its URL. In addition, `git pull` can pull from
> +**UPSTREAM** without argument.
> +
> +For each branch requiring a triangular workflow, set
> +`branch.<branch>.remote` and `branch.<branch>.pushRemote`.
> +
> +Example with master as <branch>:
> +===================================
> +* `git config branch.master.remote upstream`
> +* `git config branch.master.pushRemote origin`
> +===================================

Wouldn't it be much simpler to manage if you instead start from a
clone of **UPSTREAM** and then fork **PUBLISH** and push your work
out to the latter?  You do not have to do per-branch configuration
that way, no?  Instead you would set default.pushRemote to publish
just once, and no matter how many branches you create later, you do
not have to do anything special.

It smells like you are deliberately presenting a more cumbersome
way, as a prelude to add even more configuration that is not
necessary if you started in the right direction in the first place.

Re: [PATCHv4] Documentation: triangular workflow

[Philip Oakley]

From: "Jordan DE GEA" <jordan.de-gea@grenoble-inp.org>
> Currently, triangular workflow can be configured, but there is no
> documentation about it. A documentation is useful to keep
> configuration possibilities up-to-date.
>
> A new subsection is created in gitworkflow.
>
> Signed-off-by: Michael Haggerty <mhagger@alum.mit.edu>
> Signed-off-by: Matthieu Moy <Matthieu.Moy@grenoble-inp.fr>
> Signed-off-by: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
> ---
> Changes since v3:
> * Text reorganized to follow:
>   - Introduction
>   - Preparation
>   - Staying up-to-date
>   - Alternatively
> * Texts added to explain why we use commands in:
>   - Preparation
>   - Alternatively
>
> Documentation/gitworkflows.txt | 177 
> ++++++++++++++++++++++++++++++++++++++++-
> 1 file changed, 176 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/gitworkflows.txt 
> b/Documentation/gitworkflows.txt
> index f16c414..1ec1f63 100644
> --- a/Documentation/gitworkflows.txt
> +++ b/Documentation/gitworkflows.txt
> @@ -463,6 +463,178 @@ if you get conflicts: `git am -3` will use index 
> information contained
> in patches to figure out the merge base.  See linkgit:git-am[1] for
> other options.
>
> +TRIANGULAR WORKFLOW
> +-------------------
> +
> +In some projects, you cannot push directly to the project but have to
> +suggest your commits to the maintainer (e.g. pull requests).
> +For these projects, it's common to use what's called a *triangular
> +workflow*:
> +
> +- Taking the last version of the project by fetching from **UPSTREAM**
> +- Writing modifications and push them to a fork (e.g. **PUBLISH**)

s/a fork/an accessible fork/
Isn't one of the key points of the triangle that the user can't push to the 
upstream? (and the maintainer can't see the users local repo)

> +- Opening a pull request
s/request/request (formally or informally)/

> +- If the maintainer accepts the changes, he merges them into the
a Catch 22 here. The maintainer needs first to fetch, or othewise read, the 
mods before she could accept the changes. Perhaps

- The maintainer fetches, and reviews, the proposed changes; And if 
acceptable, merges them into the upstream.

the exact timing of the fetch will depend on the review system (see below).

> +  **UPSTREAM** repository.
> +
> +
> +........................................
> +------------------               -----------------
> +| UPSTREAM       |  maintainer   | PUBLISH       |
> +|  git/git       |- - - - - - - -|  me/remote    |
> +------------------       ←       -----------------
> +              \                     /
> +               \                   /
> +          fetch↓\                 /↑push
> +                 \               /
> +                  \             /
> +                   -------------
> +                   |   LOCAL   |
> +                   -------------
> +........................................
> +
> +Motivations
> +~~~~~~~~~~~
> +
> +* Allows contributors to work with Git even though they do not have
> +write access to **UPSTREAM**.
> +
> +* Allows maintainers to receive code from contributors they may not
> +trust.
s/trust/trust with psuh access/
It is the push/pull access issues that create the triangular workflow!

> +
> +* Code review is more efficient

more efficient than ??? in environment ??? (e.g. a review process of web 
viewing/commenting on GitHub, driven by a limited patch/mail server 
capability)


> +
> +* Encourages clean history by using `rebase -i` and `push --force` to
> +your public fork before the code is merged
> +
> +Preparation
> +~~~~~~~~~~~
> +
> +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty
> +repository.

I agree here. To clone the upstream, to which you have no push access (by 
definition), would leave the config badly mis-set for the basic user. It's 
better for the user to clone their publish fork (to which they have both 
read and write access).

One issue may be the different expectations of how the fork is created (it's 
only one click on the GitHub..)

It may be worth covering the remote rename option to set that origin to the 
short and sweet 'me', or 'my', as per the ascii diagram.

> +
> +======================
> +`git clone <PUBLISH_url>`
> +======================
> +
> +Setting the behavior of push for the triangular workflow:
> +
> +===========================
> +`git config push.default current`
> +===========================
> +
> +Adding **UPSTREAM** remote:
> +
> +===================================
> +`git remote add upstream <UPSTREAM_url>`
> +===================================
> +
> +With the `remote add` above, using `git pull upstream` pulls there,
> +instead of saying its URL. In addition, `git pull` can pull from
> +**UPSTREAM** without argument.
> +
> +For each branch requiring a triangular workflow, set
> +`branch.<branch>.remote` and `branch.<branch>.pushRemote`.
> +
> +Example with master as <branch>:
> +===================================
> +* `git config branch.master.remote upstream`
> +* `git config branch.master.pushRemote origin`
> +===================================
> +
> +Stay up-to-date
> +~~~~~~~~~~~~~~~
> +
> +Retrieve updates from **UPSTREAM** with `git pull` and send them to
> +**PUBLISH** with `git push`.
> +
> +Checks
> +~~~~~~
> +
> +.Display the push remote's name:
> +[caption="Recipe: "]
> +
> +=================================
> +`git rev-parse --abbrev-ref @{push}`
> +=================================
> +
> +The shorthand `<branch>@{push}` denotes the remote-tracking branch
> +where the <branch> would be pushed to. If no <branch> is specified
> +(`@{push}`), <branch> takes the value of the current branch.
> +
> +
> +.Display the fetch remote's name:
> +[caption="Recipe: "]
> +
> +===================================
> +`git rev-parse --abbrev-ref @{upstream}`
> +===================================
> +
> +The shorthand `<branch>@{upstream}` substitutes the upstream name of
> +the branch. If no <branch> is specified (`@{upstream}`), <branch>
> +takes the value of the current branch.
> +
> +.Display commits added to the current branch since last push:
> +[caption="Recipe: "]
> +
> +===============
> +`git log @{push}..`
> +===============
> +
> +.Display commits added to a specific branch since last push:
> +[caption="Recipe: "]
> +
> +============================
> +`git log <branch_name>@{push}..`
> +============================
> +
> +Alternative configuration
> +~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +.Cloning from **UPSTREAM**
> +[caption="Recipe: "]
> +
> +In the preparation above, a clone from **PUBLISH** was used. Starting
> +with a clone of **UPSTREAM** is possible too.
> +
> +Cloning from **UPSTREAM**
> +
> +======================
> +`git clone <UPSTREAM_url>`
> +======================
> +
> +Setting the behavior of push for the triangular workflow:
> +
> +===========================
> +`git config push.default current`
> +===========================
> +
> +Because modifications will be often pushed into the **PUBLISH** 
> repository,
> +instead of having to type its URL every time, a short name can be used
> +to call it.
> +
> +Adding **PUBLISH** remote:
> +
> +===================================
> +`git remote add publish <PUBLISH_url>`
> +===================================
> +
> +With the `remote add` above, using `git push publish` pushes there,
> +instead of saying its URL. In addition, `git push` can push to
> +**PUBLISH** without argument.
> +
> +'Method 1: One option for all branches'
> +
> +===================================
> +`git config remote.pushDefault publish`
> +===================================
> +
> +'Method 2: Each branch its option'
> +
> +Example with master as <branch>:
> +===================================
> +`git config branch.master.pushRemote publish`
> +===================================
>
> SEE ALSO
> --------
> @@ -473,7 +645,10 @@ linkgit:git-merge[1],
> linkgit:git-rebase[1],
> linkgit:git-format-patch[1],
> linkgit:git-send-email[1],
> -linkgit:git-am[1]
> +linkgit:git-am[1],
> +linkgit:git-config[1],
> +linkgit:git-log[1],
> +linkgit:git-rev-parse[1]
>
> GIT
> ---

Re: [PATCHv4] Documentation: triangular workflow

[Junio C Hamano]

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

>> +Preparation
>> +~~~~~~~~~~~
>> +
>> +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty
>> +repository.
>
> I agree here. To clone the upstream, to which you have no push access (by 
> definition), would leave the config badly mis-set for the basic user. It's 
> better for the user to clone their publish fork (to which they have both 
> read and write access).

I do not think I agree.

If you apriori know that you do want to hack on a project's code, then
forking at GitHub first and then cloning the copy would be OK.

But I doubt that would be a common set-up, unless you are focusing
only on school-like setting where you are told by your instructor to
"make changes to this public project, and show the result in your
fork".  In real life you cannot tell if the project is worth your
time modifying until you see it first, can you?

I suspect that the majority of local clones start from something
like "I want to build and use from the tip", "I want to use a module
that does X, and there are three candidates, so let's clone them all
to evaluate", etc.  You do not bother "forking at GitHub" but just
clone from the upstream for these clones.

After you build it and try things out, you may start making local
changes, and you may even record your changes as local commits.  You
play with your local clone of the upstream.  After doing so, you may
find that some of the projects do not fit your needs, but for some
others, you would find that it is worth your time and effort to
upstream your changes and/or keep working further on the project.

And at that point, you would create a publishing place, push into
it, and tell others "Hey I did this interesting thing!".  That
"creat a publishing place" step could be just a one click at GitHub.

Isn't that how you work with other people's projects?  Or do you
always modify every project you fetch from the outside world?, Do
you always fork first, just in case you *might* change and you
*might* have to have a place to push your changes out?

If you tell novices "You fork first and then clone your fork", and
in the ideal (to you) case they will follow that advice to the
letter and they will end up with forks of all projects they will
ever look at, in many of which they make no local commit.

What is more likely to happen is that they will first ignore you and
start from a local clone of the upstream, and then find this
document that says "triangular workflow requires you to fork first,
clone that fork and work in it".  Because they would have to fork
first and make another clone, this time a clone of the fork, in
order to follow the instruction of this document, they oblige,
ending up with two clones.  More importantly, this makes the local
clone of the upstream they made earlier and the changes they made in
that clone appear useless.  They need to be told how to transplant
the work done in the clone to the newly created clone of the fork,
in order to publish them.

If your instruction begins with "You clone from upstream as usual
(i.e. just like when you make a "read-only" clone without any
intention to make changes or push changes out), and add a publish
place if/when it becomes necessary", the problem described in the
previous paragraph goes away, no?

Re: [PATCHv4] Documentation: triangular workflow

[Ramkumar Ramachandra]

Junio C Hamano wrote:
> Jordan DE GEA wrote:
>
> > +* Allows contributors to work with Git even though they do not have
> > +write access to **UPSTREAM**.
> >
> > +* Allows maintainers to receive code from contributors they may not
> > +trust.

Triangular workflow is the ability to accept changes from contributors
without mailing patches back-and-forth. Whether they send a pull
request or commit directly to the master repository when review is
done, is inconsequential. Essentially, they maintain forks of
upstream, which they work on at their own pace.

> > +* Code review is more efficient
>
> I have no idea what data you have to back this claim up.  More
> efficient compared to what?

They're orthogonal. LLVM has one giant SVN server that everyone
commits directly to. However, they review process is a lot more
efficient than GitHub projects, because they use Phabricator. What
does code review tool have to do with triangular workflow?

> > +Preparation
> > +~~~~~~~~~~~
> > +
> > +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty
> > +repository.
> > +
> > +======================
> > +`git clone <PUBLISH_url>`
> > +======================
> > +
> > +Setting the behavior of push for the triangular workflow:
> > +
> > +===========================
> > +`git config push.default current`
> > +===========================
> > +
> > +Adding **UPSTREAM** remote:
> > +
> > +===================================
> > +`git remote add upstream <UPSTREAM_url>`
> > +===================================
> > +
> > +With the `remote add` above, using `git pull upstream` pulls there,
> > +instead of saying its URL. In addition, `git pull` can pull from
> > +**UPSTREAM** without argument.
> > +
> > +For each branch requiring a triangular workflow, set
> > +`branch.<branch>.remote` and `branch.<branch>.pushRemote`.
> > +
> > +Example with master as <branch>:
> > +===================================
> > +* `git config branch.master.remote upstream`
> > +* `git config branch.master.pushRemote origin`
> > +===================================

It's much too simple now. Just `git clone <upstream>`, `git remote add
mine <fork-url>`, and `git config remote.pushdefault mine`. Only the
last line requires an explanation.

> Instead you would set default.pushRemote to publish
> just once, and no matter how many branches you create later, you do
> not have to do anything special.

I think you meant remote.pushdefault here?

Re: [PATCHv4] Documentation: triangular workflow

[Philip Oakley]

From: "Junio C Hamano" <gitster@pobox.com>
> "Philip Oakley" <philipoakley@iee.org> writes:
>
>>> +Preparation
>>> +~~~~~~~~~~~
>>> +
>>> +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty
>>> +repository.
>>
>> I agree here. To clone the upstream, to which you have no push access (by
>> definition), would leave the config badly mis-set for the basic user.
>> It's
>> better for the user to clone their publish fork (to which they have both
>> read and write access).
>
> I do not think I agree.
>
> If you apriori know that you do want to hack on a project's code, then
> forking at GitHub first and then cloning the copy would be OK.
>

You've clipped my other point:

-        One issue may be the different expectations of how the fork is
-        created (it's only one click on the GitHub..)

The fork creation issue is surely an essential part of triangular workflow - 
a fork isn't required for a patch workflow. Git uses patch flow, while 
Git-for-Windows makes use of (GitHub's) Pull Requests.

Most projects will be using some form of hosting service to provide their 
public publish repo, and often allow no public pushes. It's the upstream 
that choses the hosting service, which decides the users choices.

> But I doubt that would be a common set-up, unless you are focusing
> only on school-like setting where you are told by your instructor to
> "make changes to this public project, and show the result in your
> fork".  In real life you cannot tell if the project is worth your
> time modifying until you see it first, can you?

At this point there are multiple choices depending how the hosting and 
project is set up. It may already be packaged. It may allow full web 
browsing of the code. It probably has tar/zip download of the latest master. 
Some popular sites offer free hosting and forking, which leads to the the 
suggested method.

>
> I suspect that the majority of local clones start from something
> like "I want to build and use from the tip", "I want to use a module
> that does X, and there are three candidates, so let's clone them all
> to evaluate", etc.  You do not bother "forking at GitHub" but just
> clone from the upstream for these clones.

Any stat's for this. I'd be far more likely to fork first, giving me a 
backup vault, and clone that, especially since being bitten (historically) 
by the need to juggle the configs after the fact..

>
> After you build it and try things out, you may start making local
> changes, and you may even record your changes as local commits.  You
> play with your local clone of the upstream.  After doing so, you may
> find that some of the projects do not fit your needs, but for some
> others, you would find that it is worth your time and effort to
> upstream your changes and/or keep working further on the project.

In all these cases there is the 'backup' copy question for any of those 
mods, which tends to mean the user will have a fork acting as a home vault.

>
> And at that point, you would create a publishing place, push into
> it, and tell others "Hey I did this interesting thing!".  That
> "creat a publishing place" step could be just a one click at GitHub.
>
> Isn't that how you work with other people's projects?  Or do you
> always modify every project you fetch from the outside world?, Do
> you always fork first, just in case you *might* change and you
> *might* have to have a place to push your changes out?

As noted above, yes, if I'm interested enough to go for the clone, then mods 
are a real posibility and I'd typically use the hosting service as a 
vault/triangle.

>
> If you tell novices "You fork first and then clone your fork", and
> in the ideal (to you) case they will follow that advice to the
> letter and they will end up with forks of all projects they will
> ever look at, in many of which they make no local commit.
>
> What is more likely to happen is that they will first ignore you and
> start from a local clone of the upstream, and then find this
> document that says "triangular workflow requires you to fork first,
> clone that fork and work in it".  Because they would have to fork
> first and make another clone, this time a clone of the fork, in
> order to follow the instruction of this document, they oblige,
> ending up with two clones.  More importantly, this makes the local
> clone of the upstream they made earlier and the changes they made in
> that clone appear useless.  They need to be told how to transplant
> the work done in the clone to the newly created clone of the fork,
> in order to publish them.
>
> If your instruction begins with "You clone from upstream as usual
> (i.e. just like when you make a "read-only" clone without any
> intention to make changes or push changes out), and add a publish
> place if/when it becomes necessary", the problem described in the
> previous paragraph goes away, no?
>

Yes, the document does need to cover both routes, which should be the main 
outcome of the discussion.

But I still think that, by definition of the triangular workflow (and the 
reader will be here because they are expecting to be part of that flow), 
that the fork first (if available), is to my mind, the easiest was to get 
started. And if it's not, i.e. they clone upstream first, create a publish 
server/host/repo, push to that, and adjust all the configs for that, then 
that should also be described. It all depends on the phantom 'git fork 
<upstream> <publish>` command.

E.g.
* Establishing a triangular workflow using upstream's host fork method.
You do not have a local clone of upstream yet and hope to work on the 
project with a triangular flow. /describe the easiest steps from here/

* Converting a local repo to a triangular workflow.
You already have a local clone of the upstream, but no public repo that the 
maintainer can pull from. /describe the necessary steps to set up a fork, 
and appropriate config settings/

Re: [PATCHv4] Documentation: triangular workflow

[Philip Oakley]

From: "Ramkumar Ramachandra" <artagnon@gmail.com>
> Junio C Hamano wrote:
>> Jordan DE GEA wrote:
>>
>> > +* Allows contributors to work with Git even though they do not have
>> > +write access to **UPSTREAM**.
>> >
>> > +* Allows maintainers to receive code from contributors they may not
>> > +trust.
>
> Triangular workflow is the ability to accept changes from contributors
> without mailing patches back-and-forth. Whether they send a pull
> request or

>       commit directly to the master repository

Surely, if they can do this then they do not need a distinct publish repo.

The triangle is necessary because of the accessibility 'standoff' between 
the upstream and local repos when a pull workflow is used.

Matthieu had clarified this (to me 
http://article.gmane.org/gmane.comp.version-control.git/296538) - I was (at 
that time) confusing the use of the fork as a home vault (with passive 
publishing) with the need for actively publishing a branch for a PR.

>   when review is
> done, is inconsequential. Essentially, they maintain forks of
> upstream, which they work on at their own pace.
>
>> > +* Code review is more efficient
>>
>> I have no idea what data you have to back this claim up.  More
>> efficient compared to what?
>
> They're orthogonal. LLVM has one giant SVN server that everyone
> commits directly to. However, they review process is a lot more
> efficient than GitHub projects, because they use Phabricator. What
> does code review tool have to do with triangular workflow?
>
>> > +Preparation
>> > +~~~~~~~~~~~
>> > +
>> > +Cloning from **PUBLISH**, which is a fork of **UPSTREAM** or an empty
>> > +repository.
>> > +
>> > +======================
>> > +`git clone <PUBLISH_url>`
>> > +======================
>> > +
>> > +Setting the behavior of push for the triangular workflow:
>> > +
>> > +===========================
>> > +`git config push.default current`
>> > +===========================
>> > +
>> > +Adding **UPSTREAM** remote:
>> > +
>> > +===================================
>> > +`git remote add upstream <UPSTREAM_url>`
>> > +===================================
>> > +
>> > +With the `remote add` above, using `git pull upstream` pulls there,
>> > +instead of saying its URL. In addition, `git pull` can pull from
>> > +**UPSTREAM** without argument.
>> > +
>> > +For each branch requiring a triangular workflow, set
>> > +`branch.<branch>.remote` and `branch.<branch>.pushRemote`.
>> > +
>> > +Example with master as <branch>:
>> > +===================================
>> > +* `git config branch.master.remote upstream`
>> > +* `git config branch.master.pushRemote origin`
>> > +===================================
>
> It's much too simple now. Just `git clone <upstream>`, `git remote add
> mine <fork-url>`, and `git config remote.pushdefault mine`. Only the
> last line requires an explanation.

I note that you use 'mine', Jordan was proposing 'me', while I started using 
'my'. It is useful to see these personal choices, especially as there is no 
'origin' in the nominal triangular flow diagram.

Whether to use branch configs or remote configs is part of the 
clarifications.

>
>> Instead you would set default.pushRemote to publish
>> just once, and no matter how many branches you create later, you do
>> not have to do anything special.
>
> I think you meant remote.pushdefault here?
> 

Re: [PATCHv4] Documentation: triangular workflow

[Junio C Hamano]

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

> From: "Junio C Hamano" <gitster@pobox.com>
>> I do not think I agree.
>>
>> If you apriori know that you do want to hack on a project's code, then
>> forking at GitHub first and then cloning the copy would be OK.
>
> You've clipped my other point:
>
> -        One issue may be the different expectations of how the fork is
> -        created (it's only one click on the GitHub..)

Not really.  I said the same thing paraphrased:

    And at that point, you would create a publishing place, push into
    it, and tell others "Hey I did this interesting thing!".  That
    "create a publishing place" step could be just a one click at GitHub.

Anyway, let's step back a bit and agree that your local clone needs
to be told 4 pieces of information to help you in a triangular
workflow.  They are:

 * The URL of the "upstream";
 * The URL of the "publish" (aka "mine");
 * Your push should go to "publish" by default; and
 * Your pull should come from "upstream" by default.

Are we still on the same page, or have we already diverged?

If you start from a clone of "upstream", then the local clone
already knows two out of these four, namely, "The URL of the
'upstream' aka origin" and "Your pull should come from upstream by
default".  In order to go triangular, you still need to tell the
other two to your local clone, namely "There is another remote
called 'publish'" and "Your push should go to 'publish' not to
'origin'".

When you start by forking at GitHub and then cloning that fork,
would it make it easier to go triangular?  I do not think so.  The
local clone gives you (different) two out of these four, namely "The
URL of the 'publish' aka origin, which is your own fork" and "Your
push should go to 'publish'".  You still need to tell the other two,
"The URL of the 'upstream'" and "Your pull should come from
'upstream', not from 'origin'" to your local repository.

So I really do not see a point in arguing that "forking at GitHub is
easy with one click" favors "your local clone should start by
cloning your own fork".  Between starting from a clone of upstream
and starting from a clone of your own fork, it is the same amount of
work to go triangular even for people who fork before having any
clone locally, like you.

And I do not have to repeat myself that it is far more helpful to
give a recipe to go triangular starting from a clone of upstream for
people who first clone three similar projects to evaluate them,
discard two that do not suit their needs, and fork the best one, by
adding that fork as "publish" aka "mine", than giving a recipe to
start from a clone of one's own fork.

Having said that, there are indeed two interesting numbers we may
want to ask GitHub folks to help coming up with.  Take any popular
project with many public forks at GitHub, say rails with 13k forks.

 * How many "clone" from the upstream (i.e. rails/rails in this
   example) compared to 13k forks it has were made by the users?

   Many of them might be just following along (e.g. they want to
   build the tip of the tree that is ahead of any tagged released
   version), but there may be some among these local repositories
   cloned from upstream without forking that record their own
   commits.  These are the people who will benefit a version of the
   documentation under discussion if it describes how to start from
   a clone of upstream, then add your own fork as the publishing
   repository so that the user can use a triangular workflow.  I
   somehow suspect that there are a lot more than 13k (i.e. the
   number of public forks) of these people, but I do not think
   https://github.com/rails/rails page gives us the number.


 * What percentage of these 13k public forks are "empty forks",
   i.e. forked from the main project but has never been pushed into?

   It matters if the answer to this question is a non-trivial
   percentage.  It indicates that the owners of these forks did the
   "fork first and then clone from there", and had to do an extra
   work of adding the real upstream as another remote and set up to
   pull from there, if they wanted to just keep up to date; they
   would have been better off if they started by cloning the
   upstream first.