From: Jordan DE GEA Date: Mon, 06 Jun 2016 09:48:37 GMT Subject: [RFC/PATCHv2] Documentation: triangular workflow Message-ID: <1465206518-1780-1-git-send-email-jordan.de-gea@grenoble-inp.org> 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 Signed-off-by: Matthieu Moy Signed-off-by: Jordan DE GEA --- 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..remote` + - `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 ` +=================================== + +Setting `branch..remote` and `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 : +=================================== +* `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 ` +=================================== + +**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..pushRemote` in order to push to **PUBLIC-FORK** +without argument to push. + +Example with master as : +=================================== +* `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 `@{push}` denotes the remote-tracking branch +where the would be pushed to. If no is specified +(`@{push}`), 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 "@{upstream}" substitutes the name of the +"upstream" of the branch. If no is specified (`@{upstream}`), + 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 @{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)