From: Philip Oakley Date: Fri, 03 Jun 2016 07:25:27 GMT Subject: Re: [RFC/PATCH] Triangular Workflow UI improvement: Documentation Message-ID: <9FB65CA220F84B6B882B75435DDA3D65@PhilipOakley> In-Reply-To: <1464697717-5751-1-git-send-email-jordan.de-gea@grenoble-inp.org> [Just catching up with responses] From: "Jordan DE GEA" 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 > Signed-off-by: Jordan DE GEA > --- > 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..pushRemote` > +- `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 ` > +=================================== > + > +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) > >