With knowledge of these terms and what - on a more technical level - branches really are, we can begin to demonstrate how to use them.
To get started with branching, point your Git console within a repo, as is necessary for running any Git commands. We will demonstrate these tasks on a new GitHub repository with nothing but the default readme file:
Github offers a way to visualize a repository and its branches under insights -> network on the page for your repo. With our initial commit, the tree is quite bare:
As we begin to use branches, we will see how the tree allows us to visually depict how different branches are developed on parallel.
Whenever working in Git, you will be working on a particular branch (master by default). To create or switch to a branch, use:
If the “-b” argument is provided and the branch name does not exist, a new branch will be created with that name. Any uncommitted changes on your current branch will be transferred to the new branch. Then, whether the branch already existed or a new one was created, you will be switched to working on that branch.
Now make a new file, with some basic contents, and commit it to the repo. We will use the following example:
Pushing a branch to a remote repo (such as on GitHub) requires a special command if the branch does not exist there yet (otherwise just push normally):
When this is done, we may view the branch in our repository on GitHub. By using the small dropdown on the top left to select the current branch. First, we notice that our commit and corresponding file are not in the repository by default. This is because we are viewing the main branch and not our new branch. When viewing the new branch, we see that our changes are there.
Now, use the git checkout command to switch back to the main branch. You will notice that any new changes in the branch you created are missing. This is because they are only on that branch! We now make a change here, to demonstrate how the two branches can be developed independently:
Now we may commit this file, and view the revision tree, which will reveal what our repository looks like now with its two branches, each with their own different "code":
As we can see, the two branches are now split from the point we made the new branch, and each has their own commits with different content.
GitHub also provides a user interface on the website for creating and managing branches. By clicking on "branches" next to the branch selection dropdown when viewing the repo, you will be able to view the branches that have been created. Here you can manage and navigate between branches. To delete a branch, click the small trash can icon for the branch you wish to remove.
Returning to the homepage for the repo, typing a non-existent branch name in the branches dropdown and hitting enter will create a new branch from the one currently being viewed.
In summary, we have learned how to use branches. From this guide you should know how to:
Push branches to a remote repository
View them on GitHub
Add files and code to them independently
Visualize the revisions and branching history in a tree-like view
Create and manage branches through GitHub's interface instead of the terminal
Now that you understand the power of branches in Git, it is pretty clear to see not only how they are useful, but also how they may be complicated and easy to trip yourself up over. To get the most out of branching, developers tend to follow these best practices to keep things organized, sidestep error-prone areas of the process, and to manage their projects from a deployment point of view.
By doing this, developers can guarantee they have a copy of the codebase that is 100% functional and able to be shipped to clients/users/customers. More than that, this provides a branch where there is known, tested, bug-free code for other branches to be based off of, so that new features being developed do not have irrelevant issues from other work-in-progress code. Some projects go as far as to assign roles to users in the repository, such that only special leaders in the project can approve merge requests into Main/Master, even though everybody is allowed to submit them.
This makes logical sense as coding different features, probably independent and having no inter-related code, does not require users to work on the same branch. It also provides a good way to organize what is being worked on within the project. Finally, branches are a great way to keep experimental, possibly broken code that won't be used within the revision control system when being developed, and potentially to be revisited, without affecting the functionality of the main copy of the codebase.
Especially when following the above practices, merge requests become times when everyone on a project can view all of the commits and revisions for a particular, complete feature, before deciding to integrate it. This holistic view allows for evaluation of the end result better than doing code reviews commit-by-commit. Then, when merging into Main/Master, the code being merged represents a working piece of specific functionality, approved and tested by the team, with any issues ironed out through the built in issue tracking and commenting/discussion features that developers can use to communicate.
Doing so may lead to a mess of code that is impossible to untangle, and even the abort command may corrupt the uncommitted changes you have. The Git documentation itself warns against doing this ().
Before we begin, a more technical introduction to branching and merging is necessary to introduce some concepts, terminology, and conventions.
Branches are where code and revisions are committed and pushed to. In a repo, by default, any work done is done on the default “master” (sometimes called “main”) branch. New branches are created as copies of other “source” branches, that is, when a new branch is created from a source branch, everything – all files, content, and revision history - in the source branch is copied to the new branch. From then on, commits and changes are managed independently in both branches and do not affect each other, and developers can choose what branch to push their changes to. For example, if branch B is created from branch A, one can commit code to branch B, and nothing will change in the copy of the codebase stored in branch A.
Merging allows one to combine two branches, transferring the changes from a branch (again called the source branch) to another branch (called the destination branch). In doing this, all differences in revisions between the source and destination are committed to the destination branch. Sometimes, there are conflicts, where both branches made changes to the same code, in which case the user is required to resolve the conflicts in a so-called merge commit where the user picks what code from each branch should be incorporated (or writes their own code so that both sets of changes can work together).
Now, we will dive into the details of creating, managing, and merging branches. We will walk the user through the following:
Creating branches
Switching to a branch to make a change
Merging a branch
Resolving simple conflicts when merging code
How GitHub provides an alternate and easy to use GUI for the above tasks
When we wish to combine the changes in two branches. We do this by merging them.
To merge, switch branches to the desired destination branch (we will use main, continuing with our example as before) and run
If there are so-called conflicts, conflict markers (determined by <<<<<<<, representing the code in current branch, or >>>>>>>, representing the new, conflicting code. They are separated by =======) will be in the files, and the user must resolve all conflicts (make sure to remove the markers, too), making necessary changes to ensure the code from both branches works. Conflicts occur when two branches make changes to the same piece of code, which makes it unclear which to keep or how to combine them.
When this is done, commit your changes. Then you should run:
and then push your changes to the remote repository. To abort a merge, run:
In scenarios where there are no conflicts, git merge should work immediately.
Manually resolving conflicts like this is important to know how to do, but can be difficult and time-consuming. GitHub provides an interface for doing this, with an automatic merging algorithm. It will also tell you when things are too complicated for it to figure out, and to complete the merge manually as we have shown above in cases where you absolutely must. But usually, a merge completely on the GitHub UI is possible. In any case, it is always worth creating the so-called "pull request" to merge two branches on GitHub for three reasons:
The request will be on GitHub for other coworkers to see, letting them to comment, review the code, and agree with you to merge it before moving forward. Merging is as much a communication tool as it is a code management tool, and leaving a paper trail when you do it is important for the same reasons as using revision control in the first place
The aforementioned automatic merging feature is far easier to use than merging manually and locally
If you still need or want to merge manually and locally, it is still possible to do so
To execute a merge on GitHub, click on the "Pull Request" button, which will be in a bar under the main navigation bar with the branches dropdown.
This opens the pull request window, where GitHub will notify you if an automatic merge is possible, and for you to name the request and leave a description/comments before submitting with the button on the bottom right:
In our example case, we see that the automatic merge can not be completed. In the pull request window you will be routed to after creating it (or accessible by navigating to the pull requests tab), there will be a button to resolve conflicts, among the other features of the merging UI on GitHub such as commenting, and - ultimately - approval of the request.
To resolve conflicts in GitHub, clicking that button will lead you to a window showing you the conflicts and letting you decide what to do, much like in the manual case. Other hosts for Git (ie. GitLab) may offer a user interface that lets you pick and chose what code from what branch to keep.
In our example here we can resolve the conflict by including the contents of both files:
With no more conflicts, we use the "Mark as Resolved" button on the top right and the "Commit Merge" button that pops up.
It is worth noting that at this point the merge has not been executed, just - whether a commit was created to resolve conflicts or not - that it is ready to be merged. To actually execute the merge, use the "Merge Pull Request" button that should appear once there are no conflicts.
With the merging complete, we may now view how our two example branches have "converged" as our new branch was integrated into main through the merge:
The additional commit on the example branch was the commit where we resolved the merge conflicts.
In summary, you now know how to combine code in different branches back together, once they are done being worked on. Specifically, we covered:
Starting the merge process in the command line
What merge conflicts are
How to resolve conflicts
How to complete or abort a merge in the command line
How to request merges (called "Pull Requests") on GitHub
How to resolve conflicts that GitHub cannot automatically resolve within the web interface
How to approve merges on GitHub, thereby executing the desired merge
What merged branches look like in the revision tree
