From: Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
To: git@vger.kernel.org
Cc: mhagger@alum.mit.edu, philipoakley@iee.org, gitster@pobox.com,
erwan.mathoniere@grenoble-inp.org, samuel.groot@grenoble-inp.org,
tom.russello@grenoble-inp.org, Matthieu.Moy@grenoble-inp.fr,
Jordan DE GEA <jordan.de-gea@grenoble-inp.org>
Subject: [RFC/PATCHv2] Documentation: triangular workflow
Date: Mon, 6 Jun 2016 11:48:37 +0200 [thread overview]
Message-ID: <1465206518-1780-1-git-send-email-jordan.de-gea@grenoble-inp.org> (raw)
In-Reply-To: <1464697717-5751-1-git-send-email-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 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)
next prev parent reply other threads:[~2016-06-06 9:49 UTC|newest]
Thread overview: 41+ messages / expand[flat|nested] mbox.gz Atom feed top
2016-05-26 10:06 [RFC] Triangular Workflow: user friendly full implementation Jordan DE GEA
2016-05-26 11:04 ` Matthieu Moy
2016-05-26 18:30 ` Junio C Hamano
2016-05-30 8:46 ` [RFC] Triangular Workflow UI improvement Jordan DE GEA
2016-05-27 7:32 ` [RFC] Triangular Workflow: user friendly full implementation Philip Oakley
2016-05-30 9:07 ` [RFC] Triangular Workflow UI improvments Jordan DE GEA
2016-05-31 12:28 ` [RFC/PATCH] Triangular Workflow UI improvement: Documentation Jordan DE GEA
2016-05-31 14:33 ` Matthieu Moy
2016-06-01 9:32 ` Jordan DE GEA
2016-06-02 12:02 ` Michael Haggerty
2016-06-03 7:25 ` Philip Oakley
2016-06-03 9:52 ` Jordan DE GEA
2016-06-03 11:36 ` Matthieu Moy
2016-06-03 11:53 ` Jordan DE GEA
2016-06-05 21:28 ` Jordan DE GEA
2016-06-06 7:58 ` Matthieu Moy
2016-06-06 16:46 ` Philip Oakley
2016-06-06 16:54 ` Matthieu Moy
2016-06-06 19:21 ` Philip Oakley
2016-06-07 7:03 ` Matthieu Moy
2016-06-07 20:08 ` Philip Oakley
2016-06-03 15:46 ` Junio C Hamano
2016-06-03 22:16 ` Philip Oakley
2016-06-06 9:48 ` Jordan DE GEA [this message]
2016-06-06 19:23 ` [RFC/PATCHv2] Documentation: triangular workflow Junio C Hamano
2016-06-06 22:21 ` Philip Oakley
2016-06-07 6:58 ` Matthieu Moy
2016-06-07 8:02 ` Jordan DE GEA
2016-06-07 8:38 ` [PATCHv3] " Jordan DE GEA
2016-06-07 19:12 ` Junio C Hamano
2016-06-08 8:37 ` Jordan DE GEA
2016-06-08 13:20 ` Matthieu Moy
2016-06-09 12:35 ` [PATCHv4] " Jordan DE GEA
2016-06-09 17:02 ` Junio C Hamano
2016-06-11 15:58 ` Ramkumar Ramachandra
2016-06-11 19:31 ` Philip Oakley
2016-06-09 18:19 ` Philip Oakley
2016-06-10 16:47 ` Junio C Hamano
2016-06-11 19:25 ` Philip Oakley
2016-06-13 18:35 ` Junio C Hamano
2016-05-30 8:39 ` [RFC] Triangular Workflow UI improvement Jordan DE GEA
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1465206518-1780-1-git-send-email-jordan.de-gea@grenoble-inp.org \
--to=jordan.de-gea@grenoble-inp.org \
--cc=Matthieu.Moy@grenoble-inp.fr \
--cc=erwan.mathoniere@grenoble-inp.org \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=mhagger@alum.mit.edu \
--cc=philipoakley@iee.org \
--cc=samuel.groot@grenoble-inp.org \
--cc=tom.russello@grenoble-inp.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).