[PATCHv3] Documentation: triangular workflow

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxxxx>
Signed-off-by: Matthieu Moy <Matthieu.Moy@xxxxxxxxxxxxxxx>
Signed-off-by: Jordan DE GEA <jordan.de-gea@xxxxxxxxxxxxxxxx>
---
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)

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]