Working with Git Branches

In the most general sense branching, in version control and software configuration management, is the duplication of an object under version control such that the object can thereafter be modified separately and in parallel. It is through branching that we can maintain separate streams of work and also stay connected to other peoples work on whom we may depend.

The first question that should be asked and answered: when and how should a project be branched? It can be a challenge to choose the right strategy, but, we dont have to reinvent the wheel here. Over the years many branching strategies have been developed that form good models.

Branch Strategies

Cascade can be configured to work with any branching strategy, the system is completely agnostic on this front. Work in the way that makes sense to your project. For the sake of those new to Git, we present a few common options that are well documented and widely used.

GitHub Flow

This is by far simpler to understand and implement. Many web development teams use a functionally equivalent model of This model is well suited for software that is only ever released as the latest version to a single installation. This is often the case for a singleton website.

From the GitHub Flow documentation:
GitHub flow is a lightweight, branch-based workflow that supports teams and projects where deployments are made regularly. This guide explains how and why GitHub flow works.

Read More about GitHub Flow: https://guides.github.com/introduction/flow/

Git Flow

If you are maintaining a platform that is expected to be deployed and maintained in multiple versions, this is a model to consider because it offers long running releases that can be maintained and cross-pollinated as necessary. Though it has may great properties, this model does come with complexity in management. Thankfully there are tools out there to help enforce the model and work alongside many Git clients.

Read more about Git Flow: https://nvie.com/posts/a-successful-git-branching-model/

Creating a new Branch

After you have cloned a Git project to your local workstation, it is typical to create a branch to keep your changes distinct from the others while you work. Later on, those changes will need to be merged with the rest of the project.

A simplified workflow for making changes to a Git project is:

  1. Clone the repository you wish to work in.
  2. Create a branch based on the main/master to contain the changes.
  3. Make changes to the files.
  4. Check the changes into your local Git repository.
  5. Keeping in mind that Git is distributed, push those changes to a remote server (GitLab in this case) where others on the team can see them.

On the commandline, creating a new branch will look something like the following. Note that actual CLI commands are given special markup and preceded by a $.

  1. Open your CLI/Terminal program.

  2. Change your working directory to inside the git repository. The default operating principle of Git is that your current directory is within a repository.

    $ cd /home/example/project

  3. Checkout the branch you would like to base your changes on. In many projects, this branch is named either master or main.

    $ git checkout main

  4. Issue a git branching command to create the new branch. The following command creates a new branch called “desired-branch-name” if it does not already exist.

    $ git checkout -b desired-branch-name

  5. Make some changes to the existing files or even add a few new ones.

  6. Use the status command to see what you have changed. It will list any modifications or files that are new. Take note that the paths listed are relative to the repositories top-level directory.

    $ git status

  7. For any files that are new or changed, issue the git add command to mark each one for inclusion.

    $ git add path/to/added-or-changed/files path/to/other/modified/files […]

  8. When you are ready to save the changes into the local Git repository, you use the commit command. You should always use the -m flag to write a note describing what you changed. This helps figure things out later if needed.

    $ git commit -m ‘some message describing your changes’

  9. Remember that Git is a distributed system, and for others to see what you have changed, you will need to push them to a remote system. The default for git is to name that system “origin”

    $ git push origin desired-branch-name

More resources to learn Git branching:

Merging A Branch

If your team is following best practice of making your changes in a branch, the next step is to merge those changes into the appropriate branch. For this section we are assuming you are using GitHub Flow or any other so-called Mainline branching methodology where there is a single branch all changes are merged into called master, main, or trunk.

Depending on your team’s workflow, you can merge these changes locally or push them to a remote location for review.

Local merge workflow

For teams who do not have a review process, you can use this workflow in the beginning to merge directly into the target branch. For teams with review process, you should probably be pushing your branch to the origin and creating a merge request.

  1. Ensure you have all your changes checked into your branch.

  2. Check out the branch you would like to add your changes into (master in this case).

    $ git checkout master

  3. Be sure your local copy has the latest changes from the origin by issuing a pull command.

    $ git pull origin master

  4. Execute a merge command to add your changes to the local copy of master branch. Using the previous example the branch containing your changes was desired-branch-name

    $ git merge desired-branch-name

  5. You will see status messages and, if Git does not notify there were conflicts, it will display what merging strategy was used to add your changes to the mainline branch.

  6. To make Cascade and others aware of these changes you must push them to the Cascade GitLab. Remember: if the branch you are working on (master in this case) is being watched by Cascade, this will trigger a deploy to the configured environment.

    $ git push origin master

Merge/Pull request workflow

For teams with a review process or if you are following the GitHub Flow model, you do not merge into master branch locally, instead, you push the branch with changes to the origin and submit a merge request for it.

More information on merge requests in gitlab: https://docs.gitlab.com/ee/user/project/merge_requests/