Skip to Content

Github Branching and Merging

Remember: Git is a code repository system, while GitHub is a cloud application for managing projects that use Git for their repository. You cannot blindly follow instructions that you find on the web for doing something in Git without understanding how it will interact with GitHub! Git does not care if there is a central “official” repository, but GitHub does (and it is the central, official repository).

Git’s homepage has a subtitle, “local branching on the cheap” – and this is true, but you must know what “local” means. When you use “git clone” to make a copy of your GitHub repository, it really does clone the repository. Not only does it set you up a workspace of visible files, but it also downloads the entire repository history. You now have a local repository – and this is what Git treats as “local”. This repo is in the directory “.git” under the root directory of your workspace (which is usually “hidden” because the directory listing command ls hides names beginning with dot unless you provide the -a option).

Thus, if you use Git commands to create, manage, and delete branches, this is happening on your local Git repo, not on GitHub. You can, with the right options and command sequences, push these branches to GitHub, but you need to know what you are doing.

For course project teams, I strongly recommend that you create, manage, merge, and delete branches only through the GitHub interface.

After the Sprint 1 Demo, all project work must be done on branches, not on the main branch (main is the default “branch” that every repository has, although sometimes you will see it named master in some repositories). To do this, follow the instructions below.

  1. I recommend creating one branch per team member; each team member will then use their own branch for their own work for the duration of the project. Having a long-running development branch will mean that you will have to merge the main branch into your development branch to get the work that other team members have contributed to the main branch. Don’t wait to merge until the end of a sprint; merge early and often (in both directions). The longer you wait to merge, the more likely you will have conflicts. NOTE: This is a simpler model of using Git branches than most professionals would use; they would use at least one branch per team member per demo, or even better, one branch for each small cohesive piece of work needed done.

  2. Create a branch by clicking on the branch button when in the GitHub code view – you can type in a new branch name, preferably the name of the team member it is for. Then do a pull from GitHub to your local repo, and the branch will be available locally.

  3. You must use the “git checkout branchname” on your repository to switch to the branch you have created. This command auto-magically changes all of your workspace files to match what is on the branch. Initially, they will be the same as the main branch. You can do “git checkout main” to switch back to the main branch, but it is important to know what branch you are currently on – the command “git branch –all” will list the branches and put a ‘*’ on the one you are on. (Note: you must do a git pull on each branch to pull remote changes into your local repository and workspace; this means doing a checkout to switch to that branch and then doing a pull; then you can checkout your development branch again).

  4. Once you have switched to your development branch, work on your files. You can commit and push as often as you like, these will all affect only your branch and so will not affect your teammates, who are working on other branches. As you work, if your teammates have pushed any of their work to the main branch, you should merge their work with yours (see the next section below).

  5. Once you are done, or even close to done, on the work you want to do in your branch, merge any last changes that have been made on main into your branch, re-test your code, and then go to GitHub and issue a Pull Request. To do this, make sure you are on your development branch in the GitHub code view, then click the big green “Compare and Pull Request” button. Near the top it should say base:main <-- compare:<branchname> and then hopefully “Able to merge”. Write a description of what you are merging, and hit the “Create Pull Request” button at the bottom.

  6. Assuming there are no conflicts, you will get a green “Merge pull request” button. Use this, and leave its drop-down selection set as “Create merge commit”. Do not select the squashing or rebasing options.

  7. After your successful merge of your development branch back into the main branch, you can continue working on your branch. If you were using per-work-item branching, then you could hit the “delete branch” button if you want. But it is OK and perhaps better to leave work-item branches around for a bit, perhaps until the end of the sprint, when the team together can clean up the branches on GitHub.

If your merge shows conflicts with the main branch, you can edit files to resolve the conflicts right in GitHub, see https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-on-github or you can resolve them using the command line in your own repo (the page above has a link to command-line merge resolution), and then push the changes.

Working on a Long-lived Developer Branch

In the above section I recommend creating a developer branch and not deleting it after you have pulled your work into the main branch, but rather continuing to use it to do more work on. To do this you need to pull the changes on main that other team members have pushed into your own development branch. Recall that you must do a git pull on each branch to pull remote changes into your local repository and workspace; this means doing a checkout to switch to main and then doing a pull; then you can checkout your development branch again.

When you are in your workspace and have your own branch checked out, then you can do:

git merge main

And this will (attempt to) merge whatever is on the main branch into your branch. There are lots of options here but usually the simple operations are good enough for simple projects (like yours). But, you should make sure that you have committed (and possibly pushed) the current changes on your branch before you try to merge other changes in. If there are conflicts, the merge will be suspended and you will need to edit files that have sections delineated by lines of ‘««««’, “========”, and ‘»»»>’ characters. These lines show file differences that git was not able to automatically merge. You need to edit them to whatever they need to be, and then continue the merge (i.e., re-issue the merge command).

Atlassian tutorial on Git merge (Atlassian has lots of good Git tutorial content, but this is about Git, not GitHub).

An entire Git book is online; it includes handling basic branching and merging and advanced merge issues. (But this is about Git, not GitHub).

GitHub also has lots of online help; e.g., for pull requests, branches, resolving merge conflicts, and using Git.