1-2 hours git branching tutorial and practice in team
3-4 hours wsl2 installation and linux basic
By the end of Day 2, students will be able to:
- Execute a Feature Branch Workflow in a team environment
- Understand and resolve merge conflicts - Open and manage Pull Requests (PRs) - Install and configure WSL (Windows Subsystem for Linux) - Navigate the Linux File System using basic Bash commands and often used command for software and file management.
- why branching? Centerized development vs feature branching
- Fist step for branching
- Pull request & Merge
- Sync your repository
- Play with the game to understand the concept and commands
- Join MRAC github orgnization
- start your team project
- Create multiple branch
- Create PRs and merge to main branch
For a thorough discussion on the pros and cons of Git compared to centralized source code control systems. There are plenty of flame wars going on there. As a developer, I prefer Git above all other tools around today. Git really changed the way developers think of merging and branching. From the classic CVS/Subversion world I came from, merging/branching has always been considered a bit scary (“beware of merge conflicts, they bite you!”) and something you only do every once in a while.
But with Git, these actions are extremely cheap and simple, and they are considered one of the core parts of your daily workflow, really. For example, in CVS/Subversion books, branching and merging is first discussed in the later chapters (for advanced users), while in every Git book, it’s already covered in chapter 3 (basics).
As a consequence of its simplicity and repetitive nature, branching and merging are no longer something to be afraid of. Version control tools are supposed to assist in branching/merging more than anything else.
Enough about the tools, let’s head onto the development model. The model that I’m going to present here is essentially no more than a set of procedures that every team member has to follow in order to come to a managed software development process.
The repository setup that we use and that works well with this branching model, is that with a central “truth” repo. Note that this repo is only considered to be the central one (since Git is a DVCS, there is no such thing as a central repo at a technical level). We will refer to this repo as origin, since this name is familiar to all Git users.
Each developer pulls and pushes to origin. But besides the centralized push-pull relationships, each developer may also pull changes from other peers to form sub teams. For example, this might be useful to work together with two or more developers on a big new feature, before pushing the work in progress to origin prematurely. In the figure above, there are subteams of Alice and Bob, Alice and David, and Clair and David.
Technically, this means nothing more than that Alice has defined a Git remote, named bob, pointing to Bob’s repository, and vice versa.
At the core, the development model is greatly inspired by existing models out there. The central repo holds two main branches with an infinite lifetime:
- master
- develop
The master branch at origin should be familiar to every Git user. Parallel to the master branch, another branch exists called develop.
We consider origin/master to be the main branch where the source code of HEAD always reflects a production-ready state.
We consider origin/develop to be the main branch where the source code of HEAD always reflects a state with the latest delivered development changes for the next release. Some would call this the “integration branch”. This is where any automatic nightly builds are built from.
When the source code in the develop branch reaches a stable point and is ready to be released, all of the changes should be merged back into master somehow and then tagged with a release number. How this is done in detail will be discussed further on.
Therefore, each time when changes are merged back into master, this is a new production release by definition. We tend to be very strict at this, so that theoretically, we could use a Git hook script to automatically build and roll-out our software to our production servers everytime there was a commit on master.
Next to the main branches master and develop, our development model uses a variety of supporting branches to aid parallel development between team members, ease tracking of features, prepare for production releases and to assist in quickly fixing live production problems. Unlike the main branches, these branches always have a limited life time, since they will be removed eventually.
The different types of branches we may use are:
- Feature branches
- Release branches
- Hotfix branches
Each of these branches have a specific purpose and are bound to strict rules as to which branches may be their originating branch and which branches must be their merge targets. We will walk through them in a minute.
By no means are these branches “special” from a technical perspective. The branch types are categorized by how we use them. They are of course plain old Git branches.
May branch off from:
develop
Must merge back into:
develop
Branch naming convention:
Anything exceptmaster, develop, release-*, or hotfix-*
Feature branches (or sometimes called topic branches) are used to develop new features for the upcoming or a distant future release. When starting development of a feature, the target release in which this feature will be incorporated may well be unknown at that point. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into develop (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).
Feature branches typically exist in developer repos only, not in origin.
When starting work on a new feature, branch off from the develop branch.
git checkout -b myfeature develop
Finished features may be merged into the develop branch to definitely add them to the upcoming release:
git checkout develop
# Switched to branch 'develop'
git merge --no-ff myfeature
Updating ea1b82a..05e9557
(Summary of changes)
git branch -d myfeature
# Deleted branch myfeature (was 05e9557).
git push origin develop
The --no-ff flag causes the merge to always create a new commit object, even if the merge could be performed with a fast-forward. This avoids losing information about the historical existence of a feature branch and groups together all commits that together added the feature. Compare:
In the latter case, it is impossible to see from the Git history which of the commit objects together have implemented a feature—you would have to manually read all the log messages. Reverting a whole feature (i.e. a group of commits), is a true headache in the latter situation, whereas it is easily done if the --no-ff flag was used.
Yes, it will create a few more (empty) commit objects, but the gain is much bigger than the cost.
May branch off from:
develop
Must merge back into:
develop and master
Branch naming convention:
release-*
Release branches support preparation of a new production release. They allow for last-minute dotting of i’s and crossing t’s. Furthermore, they allow for minor bug fixes and preparing meta-data for a release (version number, build dates, etc.). By doing all of this work on a release branch, the develop branch is cleared to receive features for the next big release.
The key moment to branch off a new release branch from develop is when develop (almost) reflects the desired state of the new release. At least all features that are targeted for the release-to-be-built must be merged in to develop at this point in time. All features targeted at future releases may not—they must wait until after the release branch is branched off.
It is exactly at the start of a release branch that the upcoming release gets assigned a version number—not any earlier. Up until that moment, the develop branch reflected changes for the “next release”, but it is unclear whether that “next release” will eventually become 0.3 or 1.0, until the release branch is started. That decision is made on the start of the release branch and is carried out by the project’s rules on version number bumping.
Release branches are created from the develop branch. For example, say version 1.1.5 is the current production release and we have a big release coming up. The state of develop is ready for the “next release” and we have decided that this will become version 1.2 (rather than 1.1.6 or 2.0). So we branch off and give the release branch a name reflecting the new version number:
git checkout -b release-1.2 develop
# Switched to a new branch "release-1.2"
./bump-version.sh 1.2
Files modified successfully, version bumped to 1.2.
git commit -a -m "Bumped version number to 1.2"
[release-1.2 74d9424] Bumped version number to 1.2
1 files changed, 1 insertions(+), 1 deletions(-)
After creating a new branch and switching to it, we bump the version number. Here, bump-version.sh is a fictional shell script that changes some files in the working copy to reflect the new version. (This can of course be a manual change—the point being that some files change.) Then, the bumped version number is committed.
This new branch may exist there for a while, until the release may be rolled out definitely. During that time, bug fixes may be applied in this branch (rather than on the develop branch). Adding large new features here is strictly prohibited. They must be merged into develop, and therefore, wait for the next big release.
When the state of the release branch is ready to become a real release, some actions need to be carried out. First, the release branch is merged into master (since every commit on master is a new release by definition, remember). Next, that commit on master must be tagged for easy future reference to this historical version. Finally, the changes made on the release branch need to be merged back into develop, so that future releases also contain these bug fixes.
The first two steps in Git:
git checkout master
Switched to branch 'master'
git merge --no-ff release-1.2
Merge made by recursive.
(Summary of changes)
git tag -a 1.2
The release is now done, and tagged for future reference.
To keep the changes made in the release branch, we need to merge those back into develop, though. In Git:
git checkout develop
Switched to branch 'develop'
git merge --no-ff release-1.2
Merge made by recursive.
(Summary of changes)
This step may well lead to a merge conflict (probably even, since we have changed the version number). If so, fix it and commit.
Now we are really done and the release branch may be removed, since we don’t need it anymore:
git branch -d release-1.2
May branch off from:
master
Must merge back into:
develop and master
Branch naming convention:
hotfix-*
Hotfix branches are very much like release branches in that they are also meant to prepare for a new production release, albeit unplanned. They arise from the necessity to act immediately upon an undesired state of a live production version. When a critical bug in a production version must be resolved immediately, a hotfix branch may be branched off from the corresponding tag on the master branch that marks the production version.
The essence is that work of team members (on the develop branch) can continue, while another person is preparing a quick production fix.
Hotfix branches are created from the master branch. For example, say version 1.2 is the current production release running live and causing troubles due to a severe bug. But changes on develop are yet unstable. We may then branch off a hotfix branch and start fixing the problem:
git checkout -b hotfix-1.2.1 master
Switched to a new branch "hotfix-1.2.1"
./bump-version.sh 1.2.1
Files modified successfully, version bumped to 1.2.1.
git commit -a -m "Bumped version number to 1.2.1"
[hotfix-1.2.1 41e61bb] Bumped version number to 1.2.1
1 files changed, 1 insertions(+), 1 deletions(-)
Don’t forget to bump the version number after branching off!
Then, fix the bug and commit the fix in one or more separate commits.
git commit -m "Fixed severe production problem"
When finished, the bugfix needs to be merged back into master, but also needs to be merged back into develop, in order to safeguard that the bugfix is included in the next release as well. This is completely similar to how release branches are finished.
First, update master and tag the release.
git checkout master
Switched to branch 'master'
git merge --no-ff hotfix-1.2.1
Merge made by recursive.
(Summary of changes)
git tag -a 1.2.1
Next, include the bugfix in develop, too:
git checkout develop
Switched to branch 'develop'
git merge --no-ff hotfix-1.2.1
Merge made by recursive.
(Summary of changes)
The one exception to the rule here is that, when a release branch currently exists, the hotfix changes need to be merged into that release branch, instead of develop. Back-merging the bugfix into the release branch will eventually result in the bugfix being merged into develop too, when the release branch is finished. (If work in develop immediately requires this bugfix and cannot wait for the release branch to be finished, you may safely merge the bugfix into develop now already as well.)
Finally, remove the temporary branch:
git branch -d hotfix-1.2.1
Please finish the Introduction Sequence and Push & Pull -- Git Remote exercises from learn-git-branching
Start a team repository and finish the following task:
- Create a
mainbranch then add feature branch for each member - Sequentially add new commits and merge to the
mainbranch
Windows Subsystem for Linux (WSL) allows developers to run a GNU/Linux environment—including most command-line tools, utilities, and applications—directly on Windows, without the overhead of a traditional virtual machine or dual-boot setup.
- WSL2 is the latest architecture that uses a real Linux kernel and lightweight virtual machine technology. This provides full system call compatibility and significantly faster performance for file system access, making it ideal for resource-intensive tasks like robotics development and running Docker containers.
We use Ubuntu (specifically, the current Long-Term Support, or LTS, version) because:
- It is the officially recommended and most widely used distribution for ROS.
- Most ROS documentation, tutorials, and community support assume you are using Ubuntu.
- LTS releases offer stability and long-term support, which is crucial for a development environment.
Before starting, ensure your system meets these requirements:
- Windows 10/11: Must be running an up-to-date version.
- WSL2 Enabled: You must have the WSL feature enabled and set to version 2.
- Ubuntu Installed: A copy of the Ubuntu distribution installed from the Microsoft Store (e.g., Ubuntu 22.04 LTS).
- Hardware: A system with an NVIDIA GPU is required if you plan to use GPU acceleration (e.g., for simulation with Gazebo or machine learning).
If you are new to Linux, here are some fundamental commands you'll be using frequently:
| Command | Description | Example |
|---|---|---|
sudo |
Super User DO. Used to execute a command with administrative privileges (requires your password). | sudo apt update |
apt |
The package management tool on Debian/Ubuntu systems for installing, updating, and removing software. | sudo apt install nano |
ls |
List directory contents. | ls -l (lists with details) |
cd |
Change Directory. Used to navigate the file system. | cd ~ (goes to home directory) |
pwd |
Print Working Directory. Shows your current location. | pwd |
mkdir |
Make Directory. Creates a new folder. | mkdir ros_workspace |
Follow these sections to set up the necessary tools within your WSL2 Ubuntu environment.
Docker is essential for running ROS in a containerized environment, which provides consistency, isolation, and easy setup.
- Update your package list and install prerequisites:
sudo apt update sudo apt install ca-certificates curl gnupg
- Add Docker's official GPG key and repository:
sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL [https://download.docker.com/linux/ubuntu/gpg](https://download.docker.com/linux/ubuntu/gpg) | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod a+r /etc/apt/keyrings/docker.gpg echo \ "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] [https://download.docker.com/linux/ubuntu](https://download.docker.com/linux/ubuntu) \ "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \ sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
- Install Docker Engine and verify:
sudo apt update sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin sudo docker run hello-world
⚠️ Note on Running Docker: Install Docker Desktop for Windows on your Windows host. This manages the Docker daemon and integrates automatically with your WSL2 distributions.
This step is required if you have an NVIDIA GPU and intend to use it for high-performance tasks like simulation (Gazebo) or deep learning.
Prerequisites: Ensure you have the latest NVIDIA Windows Drivers and the NVIDIA CUDA Toolkit installed on the Windows host system.
- Add the NVIDIA Container Toolkit repository:
curl -fsSL [https://nvidia.github.io/libnvidia-container/gpgkey](https://nvidia.github.io/libnvidia-container/gpgkey) | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg curl -s -L [https://nvidia.github.io/libnvidia-container/ubuntu22.04/libnvidia-container.list](https://nvidia.github.io/libnvidia-container/ubuntu22.04/libnvidia-container.list) | \ sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \ sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
- Update and install the toolkit:
sudo apt update sudo apt install -y nvidia-container-toolkit
- Configure Docker to use the toolkit (if needed by your Docker setup):
sudo nvidia-ctk runtime configure --runtime=docker sudo systemctl restart docker
- Test the GPU access: Run a CUDA-enabled container to ensure your GPU is accessible:
If this command successfully outputs your GPU information, the installation is complete.
sudo docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi
You can copy from and past to the command line with:
Ctrl-Shift-C and Ctrl-Shift-V
The full syntax for a Bash command is:
command [options] [arguments]Bash treats the first string it encounters as a command. The following command uses Bash's ls (for "list") command to display the contents of the current working directory:
lsMost Bash commands have options for modifying how they work. Options, also called flags, give a command more specific instructions. As an example, files and directories whose names begin with a period are hidden from the user and are not displayed by ls. However, you can include the -a (for "all") flag in an ls command and see everything in the target directory:
ls -a /etcYou can even combine flags for brevity. For example, rather than enter ls -a -l /etc to show all files and directories in Linux's /etc directory in long form, you can enter this instead
ls -al /etc
Which options and arguments can be used, or must be used, varies from command to command. Fortunately, Bash documentation is built into the operating system. Help is never more than a command away. To learn about the options for a command, use the man (for "manual") command. For instance, to see all the options for the mkdir ("make directory") command, do this:
man lsMost Bash and Linux commands support the --help option. This shows a description of the command's syntax and options. To demonstrate, enter mkdir --help. The output will look something like this:
ls --help
Let's say you want to read the contents of one of the directories that you just found. To use this command
- you could use the full file name, such as:
ls Documents- Instead, you can use Bash's rudimentary autocompletion to do most of the work for you. Try typing:
ls DocThen press Tab
One important concept to understand is that the shell has a notion of a default location in which any file operations will take place. This is its working directory. If you try to create new files or directories, view existing files, or even delete them, the shell will assume you’re looking for them in the current working directory unless you take steps to specify otherwise. So it’s quite important to keep an idea of what directory the shell is “in” at any given time. The pwd command will tell you exactly what the current working directory is.
pwdYou can change the working directory using the cd command, an abbreviation for ‘change directory’. Try typing the following:
cd /
pwd
Most of the examples we’ve looked at so far use relative paths. That is, the place you end up at depends on your current working directory. Consider trying to cd into the “etc” folder. If you’re already in the root directory that will work fine:
cd /
cd etcBut what if you’re in your home directory?
You’ll see an error saying “No such file or directory”. But we have seen two commands that are absolute. No matter what your current working directory is, they’ll have the same effect. The first is when you run cd on its own to go straight to your home directory. The second is when you used cd / to switch to the root directory. In fact any path that starts with a forward slash is an absolute path. You can think of it as saying “switch to the root directory, then follow the route from there”. That gives us a much easier way to switch to the etc directory, no matter where we currently are in the file system:
cd /etcIt also gives us another way to get back to your home directory, and even to the folders within it. Suppose you want to go straight to your “Desktop” folder from anywhere on the disk (note the upper-case “D”). In the following command you’ll need to replace USERNAME with your own username, the whoami command will remind you of your username, in case you’re not sure:
whoami
cd /home/USERNAME/Desktop
pwdThere’s one other handy shortcut which works as an absolute path. As you’ve seen, using “/” at the start of your path means “starting from the root directory”. Using the tilde character (”~”) at the start of your path similarly means “starting from my home directory”.
cd ~
ls lists the contents of your current directory or the directory specified in an argument to the command. By itself, it lists the files and directories in the current directory:
lsFiles and directories whose names begin with a period are hidden by default. To include these items in a directory listing, use an -a flag:
ls -aTo get even more information about the files and directories in the current directory, use an -l flag:
ls -l
cd stands for "change directory," and it does exactly what the name suggests: it changes the current directory to another directory. It enables you to move from one directory to another just like its counterpart in Windows. The following command changes to a subdirectory of the current directory named orders:
cd ordersYou can move up a directory by specifying ..as the directory name:
cd ..You can also use .. more than once if you have to move up through multiple levels of parent directories:
cd ../..This command changes to your home directory—the one that you land in when you first log in:
cd ~
You can create directories by using the mkdir command. The following command creates a subdirectory named orders in the current working directory:
mkdir ordersIf you want to create a subdirectory and another subdirectory under it with one command, use the -p flag:
mkdir -p orders/2019
The rm command is short for "remove." As you'd expect, rm deletes files. So this command puts an end to 0001.jpg:
rm 0001.jpgBe wary of rm. The dreaded rm -rf / command deletes every file on an entire drive. It works by recursively deleting all the subdirectories of root and their subdirectories. The -f (for "force") flag compounds the problem by suppressing prompts. Don't do this. If you want to delete a subdirectory named orders that isn't empty, you can use the rm command this way:
rm -r orders
The cp command copies not just files, but entire directories (and subdirectories) if you want. To make a copy of 0001.jpg named 0002.jpg, use this command
cp 0001.jpg 0002.jpgIf 0002.jpg already exists, Bash silently replaces it. That's great if it's what you intended, but not so wonderful if you didn't realize you were about to overwrite the old version.
Move a file to another folder.
mv source_path destination_path
Every file and directory on your Unix/Linux system is assigned 3 types of owner, given below.
- u (user),the owner of a file is granted any of the permissions.
- g (group), group the file belongs to is granted a permission. A user- group can contain multiple users.
- o (other), all others are granted a permission.
Every file and directory in your UNIX/Linux system has following 3 permissions defined for all the 3 owners discussed above.
- r (read) file/directory may be opened for read access.
- w (write) file/directory may be opened for write/edit access.
- x (execute) file may be executed as a program/directory may be traversed.
Let’s see file permissions in Linux with examples:
ls - lreturns
drwxr-xr-x 2 username username 4096 Aug 9 13:39 Documents
-rw-r--r-- 1 username username 3771 Apr 17 2021 .bashrc
The first character
ddirectory-file
Following characters
- r = read permission
- w = write permission
- x = execute permission
- – = no permission
Format
rwxrwxrwx user group
By design, many Linux distributions will add users to a group of the same group name as the user name. Thus, a user ‘username’ is added to a group named ‘username’.
For the Directory Documents
user
user 'username' has read, write, and execute permission
group
user-group 'username' has read and execute permission
other
has execute permission
The superuser is, as the name suggests, a user with super powers. As for those super powers: root can modify or delete any file in any directory on the system, regardless of who owns them; root can rewrite firewall rules or start network services that could potentially open the machine up to an attack; root can shutdown the machine even if other people are still using it. In short, root can do just about anything, skipping easily round the safeguards that are usually put in place to stop users from overstepping their bounds.
sudo is used to prefix a command that has to be run with superuser privileges. A configuration file is used to define which users can use sudo, and which commands they can run. When running a command like this, the user is prompted for their own password, which is then cached for a period of time (defaulting to 15 minutes), so if they need to run multiple superuser-level commands they don’t keep getting continually asked to type it in.
The touch command allows you to create a file, for example
touch my_script.pywill create a new file named 'my_script' with the '.py' python extension
vscode is the python IDE we will using, you can open files and directories from the cli using the code command.
code my_script.pyadd the following to the python file
#!/usr/bin/env python3
print('hello world')Close and save the file.
Now try run the file
./my_script.pywill result in the following error:
bash: ./my_scripts.py: Permission denied
If we inspect the permissions of our newly created file using the ls -l command
-rw-rw-r-- 1 username username my_script.py
In order to able to execute the python file we need to give the user 'username' execute permission. This can be done with the chmod command. u+x will add execute permission for the user.
chmod u+x my_script.pywill result in:
-rwxrw-r-- 1 username username test.py
chmod +x my_script.pywill result in:
-rwxrwxr-x 1 username username test.py
now try to run the file again
./my_script.pyyou should see hello world