Creating a branch

Branching out for added value ๐ŸŒฒ

Time for a lame analogy (or a tree-o-logy)!

Think of any tree. Ok, not a palm tree. A tree has roots, a trunk, and a few or many branches (at least three!).

Each new branch potentially adds value to the trunk. They could make the tree three times tree'er than before, providing a resting place for tired birds. Swings can be attached to them. The branches, not the birds.

Not all branches add value. Some are a bit on the ugly side, making the birds select another tree for their recreational purposes. Some snap under the weight of an oversized pigeon (๐Ÿ“). Some branches might betray the tree and fork a new trunk (that unloyalty is practically tree-son ๐Ÿฅ).

Think of your GitHub repository as a tree, complete with roots (the repository), the trunk (the master branch), and branches (branched off the master branch). You use branches to improve the whole tree, design better resting platforms to support even more, or bigger, birds. After you are happy with your improved design, you can merge your improvements back to the master branch.

Here the master branch is your tree. Currently it supports medium-sized birds:

  ๐Ÿ•Š๏ธ
master โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’

New branches (support-big-birds, bigger-birds) can be branched off and merged back to the master branch to add value by making the tree stronger:

  ๐Ÿ•Š๏ธ                                    ๐Ÿฆ…                         ๐Ÿ˜
master โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’
           โ†“         ๐Ÿฆ… ๐Ÿฆ… ๐Ÿฆ…       โ†‘         โ†“     ๐Ÿ˜ ๐Ÿ˜ ๐Ÿ˜    โ†‘
           โ†“ โ†’ support-big-birds โ†’ โ†’         โ†“ โ†’ bigger-birds โ†’

After the merge, the branches are typically deleted, since they are now part of the (bigger, better, stronger) tree:

  ๐Ÿ˜
master โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’

Sometimes when working on a branch, you find that the beautiful idea you had did not turn into a valuable extension for the trunk. Perhaps the new branch turned out too heavy for the trunk to support, collapsing the whole tree. Maybe the branch looks like a snake, scaring off all the potential airborne dinosaur descendants. In this case, you might decide to throw the branch (scary-snake-branch) in the trash bin and not merge it back at all! The main branch (master) stays undisturbed by reptilian nightmares.

master โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’
           โ†“          ๐Ÿ ๐Ÿ ๐Ÿ
           โ†“ โ†’ โ†’ scary-snake-branch โ†’ โ†’ ๐Ÿ—‘๏ธ

Being able to iterate on a branch gives you an excellent opportunity to better your design until you feel confident to stick it to the trunk (or toss it to the bin!). It's almost like growing branches in isolation, without disturbing the tree!

In the context of this intranet robot, branches allow you to modify the robot and develop new features for it in isolation until you are ready to merge your changes to the master branch.

Let's branch again, like we did last summer!

Warning! Command-line intensive content ahead. Fear not. We provide suggestions for graphical tools, too! Even if you end up using a graphical Git client in your daily work, it is very useful to have a basic knowledge of using Git on the command-line. We will be using the macOS terminal in the examples.

Creating a local Git branch is a breeze. Open your terminal and navigate to the root of your robot directory:

cd ~/Projects/rsb-intranet-robot

Note that your Git repository directory names and locations will most likely be different!

List the contents of the directory by running ls -a:

ls -a
.       ..  .git    .gitignore  README.md   conda.yaml  robot.yaml  tasks.robot

You see a bunch of files. The .git directory is where Git "lives". You can view the files in there if you are interested. Just don't modify or delete them! ๐Ÿ˜…

Run git status:

git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Git tells the current branch is master, and that is up-to-date with the remote repository (origin/master) and that there is nothing to commit (changed, added, deleted). Run git branch to see the available branches:

git branch
* master

There is only the master branch. The asterisk (*) marks the currently selected branch. Create a new branch by running git checkout -b snake-branch:

git checkout -b snake-branch
Switched to a new branch 'snake-branch'

Running git branch confirms that there are now two branches: master and snake-branch. The asterisk (*) marks the currently selected branch:

git branch
  master
* snake-branch

Great! We are now on a new branch (snake-branch). It is identical to master branch, since we have not added, edited, or deleted anything. It is like a carbon-copy of the master branch. We can mess around in the snake-branch as much as we want without affecting anything in the master branch!

master โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’ โ†’
           โ†“          ๐Ÿ
           โ†“ โ†’ โ†’ snake-branch

Creating a new file ๐Ÿ

To get a feel of how branches work, let's add a snake (!). Create a new snake.txt file containing "Hiss!". If you are on macOS, run the following in the terminal to create the file (you can also create the file with your favorite text editor!):

echo Hiss! > snake.txt

Viewing the branch status

Running git status shows that Git has detected a new file:

git status
On branch snake-branch
Untracked files:
  (use "git add <file>..." to include in what will be committed)
    snake.txt

nothing added to commit but untracked files present (use "git add" to track)

Adding the file (staging)

Run git add snake.txt to tell Git to track the file. It's like saying: "I care about this file. Keep an eye on it!":

git add snake.txt

If you have multiple directories and files to add, you can add all of them by running git add .. It works if you have just one file, too! Use the name of the file when you want to add only a subset of available files.

Run git status to verify Git is tracking the new file:

git status
On branch snake-branch
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    new file:   snake.txt

The snake.txt file is staged, but not committed yet. You are telling Git: "I'm pretty sure I'm going to keep this one..."

Committing the file

To commit the file, run git commit -m 'Add a snake' (you are telling Git: "Yep, store this for me, thanks!"):

git commit -m 'Add a snake'
[snake-branch b06c4c1] Add a snake
 1 file changed, 1 insertion(+)
 create mode 100644 snake.txt

Running git status tells everything is committed:

git status
On branch snake-branch
nothing to commit, working tree clean

Comparing the branches

Compare the snake-branch with the master branch by running git diff master:

git diff master
diff --git a/snake.txt b/snake.txt
new file mode 100644
index 0000000..403dceb
--- /dev/null
+++ b/snake.txt
@@ -0,0 +1 @@
+Hiss!

Git tells it found one difference; the added snake.txt file. The branches are not identical anymore. The snake-branch is otherwise the same as the master branch, but it contains some additions that are not in the master branch.

If the snake.txt was a new feature for your robot, the new feature would not disturb the master branch. If you decided that your addition is excellent, you could merge the snake-branch to master branch. Then the master branch would contain all the changes you did in the snake-branch!

This is all great, but I'm a tad allergic to the command-line! ๐Ÿ˜Š

Do real developers use only the command-line? No. Some prefer command-line tools. Others prefer more visual tools. For Git, you have plenty of graphical clients available. Here's how the diff (comparison) looks when viewed in Visual Studio Code, using the GitLens extension:

Comparing branches in Visual Studio Code using the GitLens Extension

Or in GitHub Desktop:

Comparing branches in GitHub Desktop

Other graphical Git clients are available, too. You could use Fork, or Sourcetree, for example. Pick your poison! ๐Ÿงช

Maybe this snake was not the best idea. How do I get rid of it?

You decide that this new branch does not really help to make the robot bigger, faster, and stronger. How to get rid of it?

One thing to note is that the snake-branch exists only on your computer. To publish the branch to GitHub, you would push the branch to the remote repository (git push -u origin snake-branch, or clicking in your graphical Git client). Since you have not pushed anything, the poor to-be-gone branch exists only on your computer.

To remove the branch, you first need to checkout some other branch (you can not delete a branch you are currently on; you would just fall from the tree!). Checkout the master branch by running git checkout master:

git checkout master
Switched to branch 'master'
Your branch is up to date with 'origin/master'.

Delete the snake-branch by running git branch -d snake-branch:

git branch -d snake-branch
error: The branch 'snake-branch' is not fully merged.
If you are sure you want to delete it, run 'git branch -D snake-branch'.

As you can see, Git wants to make sure you don't accidentally delete stuff. "Not fully merged" means that the changes you have made in this branch have not been merged to any other branch (such as master). This means that if you delete the branch, the changes are gone. Poof! ๐Ÿ’ฅ

Since you are sure you want to delete the branch, you run git branch -D snake-branch:

git branch -D snake-branch
Deleted branch snake-branch (was b06c4c1).

Getting to the beef!

Enough theory and practice. Time to get our hands dirty! The first thing is to move the credentials away from the codebase. Having the username and the password committed in the repository is not a best practice!

Start by creating a branch. Make sure you are currently on the master branch by running git status:

git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean

Create a new branch by running git checkout -b remove-credentials:

git checkout -b remove-credentials
Switched to a new branch 'remove-credentials'

Great! Now you are ready to safely start hacking away without messing up the master branch. ๐ŸŽธ

What we learned

  • Branches allow you to develop your robot in isolation without disturbing the production robot.
  • You can use Git on the command-line, or with a visual client.
  • Git tracks your changes and makes it possible to compare them between branches.
  • Many projects use the master branch as the production branch.
  • Development branches (also known as feature branches) are branched off the master branch.
  • Development branches can be merged back to the master branch when they are "done".