What is the workflow for maintaining a forked git repository?

Question

I don’t get git. I am competent in subversion and mercurial, but I when I try to merge changes from an upstream repository and push the results to my fork on github, I always end up with duplicate commits, senseless conflicts, rebase loops, and other unexpected results. Other answers here on stackoverflow do not mention using git remote add upstream and seem to lack the detail I need to stop failing.

For example, say I start start with WorldEdit, a github repo at https://github.com/sk89q/WorldEdit On github, I fork the repo to https://github.com/Charlweed/WorldEdit Now I clone it to a local workstation on linux or Cygwin. I use the –recursive option, because WorldEdit seems to have three submodules. git clone --recursive git@github.com:Charlweed/WorldEdit.git

cd WorldEdit

Now, following the instructions on github, I set up tracking for the parent repository:

git remote add upstream git@github.com:sk89q/WorldEdit.git

Finally, I try to update the registered submodules to match what the superproject expects:

git submodule update --init --recursive

This is all I “know how” to set up. Everything is fine as I code, and check in local changes. As I pull and push to my github fork, everything seems to be simple and uncomplicated. Unfortunately, confusion starts as soon as I try to either:

1. Merge changes from the original, parent github repo into my forked github repo.
2. “rebase” my many small local commits into a single commit.

I decline to detail here the wrong things I do in my workflow :) . What SHOULD I be doing to keep up with the source repo, and have tidy commits suitable for pull requests?

Thanks!

Answer 1

GIT Development

This is how we manage our development cycle. http://nvie.com/posts/a-successful-git-branching-model/

Nothing fancy really… Each of us works on our own branch where each branch is a feature. When features get really large in scope we break them down into smaller pieces and implement each in their own branch. Making sure we merge our branches back in before moving on to the next.

That diagram seems pretty convoluted but really what it is showing is that there are only ever two permanent branches.

1. development
2. master

You can imagine Branching like this...

master->development->feature_branch

While merging like this...

master<-development<-feature_branch

So to start we have only our master branch. We then branch off a development branch which is tightly coupled with a global testing environment. Finally each of us creates our own short-lived feature_branch that we test on our own dev environments.

With this workflow we follow three rules

1. Never commit directly to master
2. Never commit directly to development
3. Always implement features from a new SHORT-LIVED branch

Feature

All new feature branches are created from development. When complete they are then merged back into development… where they can be tested among any other new changes (maybe someone else wrote at the same time) and final when everything works well it is merged into master.

Hotfix

Now technically hotfixes can be branched off of master and implemented quickly but then they need to be merged into development. Personally I prefer to implement Bug fixes the same way as a feature branch but that is up to you.

Testing

While developing your new branch you can SSH into the server (preferably a dev environment) and switch to your branch. git checkout <branch-name>

You may also need to do a git pull prior to checking out for the first time. Also git branch will tell you what branch you are on plus list all others.

GIT Deployment

Once you are ready to deploy you simply merge your development branch into master and commit+push your changes. Then SSH on to the server (Live) and do a git pull. To be CLEAR you should never need to use any other git cmd other than pull when logged on to the server. Rare cases not withstanding of course.

The idea is that your production server should be tightly coupled with your master branch. In other words never use git checkout <branch> on this server.

Tools

This one is purely on you to decide but our team prefers using a windows GUI tool called sourcetree. https://www.sourcetreeapp.com/

If you prefer CMD line that is fine. This doc helped me learn some of the basics of CMD. http://rogerdudler.github.io/git-guide/

Most of the time GIT and SourceTree handle merge conflicts really well. However sometimes you need a 3-way diff tool to help out… I HIGHLY recommend Kdiff http://kdiff3.sourceforge.net/

It integrates with SourceTree and can handle some really complex merge issues. If you do things correctly you will likely never need this.

Syncing a fork

Now something to keep in mind with Forked repos. You need to make sure you are pulling/merging upstream changes into your repo consistently before you attempt to follow your normal workflow. https://help.github.com/articles/syncing-a-fork/

When you do this it is strongly preferred that you have no outstanding commits that the upstream repository does not have. If you do then you need to make a pull request... Of course this is assuming those commits are ready for submission. (See quote for more specific rules) https://help.github.com/articles/using-pull-requests/

@JBNizet Makes a great point!

Don't, ever, work in branches that already exist on the upstream repo (i.e. master, for example). Create your own and work in these ones. Regularly update the master branch from upstream (it should always be fast-forward), and regularly rebase your own branches on master. When ready send a pull request from your branch to the upstream master branch

If we take these words into consideration then you can take this std workflow and modify it to work with the project. Ask the author how they usually proceed so that you can know which branch you should be branching off of. That way you can implement changes through your own stable branch and when ready you can do a pull request so that the author can review your changes.