Prerequisite modules: Development Software Suite (VSC)
Version control is fundamentally important to developers. Whether you are an individual working on your own design, or part of a multi-person team working on pieces of a large project, having a central repository and the ability to track and review changes is essential. Two very common tools are SVN and Git. In EiE we use Git.
Git is an excellent solution for firmware systems on which multiple developers work. Git uses a server or central host (very often cloud-based) as the storage and distribution point for code. Larger companies may host their own Git server, while smaller organizations may use commercial cloud-based services. For EiE, we use Github – arguably the most popular open source Git service available. All EiE participants are encouraged to open a GitHub account and learn how to actively participate as that can be beneficial to you later on. You should not use Github for anything proprietary because it is all public domain.
GitHub
All the course firmware version control is managed in GitHub under the “eiefirmware” user account (https://github.com/eiefirmware). The things you need to know for now are:
- Firmware is organized in a tree-like structure where the “master” code is the main source.
- Branches are created where new development or features are added.
- All related branches (including the master branch) are stored together in a “repository” or “repo” for short. The repo holds all the code along with all the history of branching and updates. This is extremely important for developers, as they can carefully control, share, and review code, while at the same time reverting back to any previous version in the history.
- You can “Fork” a repository into your account to work on your own version
- Users “clone” (duplicate) the online code to their local machines to make changes either explicitly by downloading it, or by checking out branches through GitHub.
- Updated code can be pushed back online to the same branch or up the tree – Git provides a good way to review changes and pull them in to the main code, and GitHub presents that in a decent graphical user interface.
- Git is natively command-line based and the full feature set is only available that way. However, the GUI interface to GitHub (called GitHub Desktop) makes it easy to use for EIE.
To get started, create a user account on GitHub (www.github.com). Choose a user name that you would be ok with providing to a potential employer, teacher, or colleague. In this example, the user is “JRL0xFF” Make sure you are logged in.
Given the way Git works there are lots of ways to manage the source code. A nice branching model is here. EiE will use Git in a slightly different way, where a main (Master) branch will contain the starting source code for most of the modules, and you will create a branch to work in for every activity. That way, the working code base is not disrupted, and you can easily switch to different module work. By the end of the program, you will have a branch for each module.
For this introduction to Git, we will start with the “Master” branch of the “razor_sam3u2_vsc” repository https://github.com/eiefirmware/eie_sam3u2_vsc
One way to get the code is to simply download a copy by selecting the “<> Code” button and choosing “Download ZIP” but that just gives you an uncontrolled copy and you forgo any advantages of using Git.
Instead, load up the Git interface you intend to use, whether it be GitHub Desktop, a command-line tool, or a built-in Git tool in VS Code like GITLENS. For this example we will use GitHub Desktop for Windows. Note there is also a quick Git Bootcamp right off the main Github page that explains the basics a bit more.
When using Git properly, you typically end up with a single code base on your computer that is the current branch that you are working with. If you change branches, your local code is automatically updated with the current code for the branch in Github. If you have changes, you will be warned to abandon them or commit them. Committing in Git is a local operation. Once committed, the changes can also be synchronized / uploaded to the repo in the cloud.
If you want to move updates from a branch back up the tree you use “Pull requests” to offer your changes to the branch manager (which might be you) who can review them and decide to merge them or not. For example, if you branched “Master” for this exercise and discovered a bug, you could fix the bug and send a pull request for the Master branch to pick up your change. Git can take that code and update the Master branch and alert any other branches that an update has been made. It would make sense that all branches should receive that code. You just have to be careful when propagating any change. In many cases, the change is made and all is well. However, if another branch has also changed code that is supposed to be updated, then a “merch conflict” can occur and you have work to do to understand what changes are trying to happen and properly synchronize everything. This can become quite a mess, so a diligent branching model, careful administration, and regular code submissions are critical for success. EiE will keep things simple so this shouldn’t come up, but keep it in mind as you build your experience with Git or any other version control software.
Managing course code in Git
Follow through this exercise to ensure you can access the online code and get a local copy on your computer. It is assumed that you have GitHub Desktop installed and are subscribed to or at least can find “eiefirmware “on GitHub.
Go to the “eiefirmware” user in Github and open the “razor_sam3u2_vsc” repository. Use the “Fork” button to bring a copy of the entire repository to your own account.
Look carefully at the image below. Use the default information and ensure the “Copy the master branch only” box is checked so you don’t get all the completed modules (you can always reference them later). Then click “Create fork.”
You should now see the forked copy of the razor_sam3u2_vsc repository in your own GitHub account. Even though it’s forked, you can still make push and pull requests to the original repository though it’s unlikely you’ll do that in EiE.
At the top left, select the “Master” branch. This is the branch you will use for the majority of the modules in EiE. Then click “<> Code” and select “Open with GitHub Desktop.”
Choose a folder name that you know will be used by Git – this is really important, because Git will be managing files in this folder. Don’t ever use this folder for anything else. Click “Clone” and wait for the files to download and add themselves into Github Desktop.
Once the download is complete, click Repository > Show in Explorer
Note the file path as that’s what you need to point VS Code to. Open VS Code and choose “Open Folder” from the Welcome screen, or File > Open Folder…
Expand the folder tree so you can see user_app1.c and open the file. Type a line in the comment section similar to what is shown below. Save the file.
Switch over to GitHub desktop and note the change.
You should get a message asking what to do with the outstanding changes on the Master branch.
In most cases, you would not want to changes branches without first dealing with changes on the current branch. You have three main choices: Commit, Stash, or Discard. In this case, Cancel the branch switch. Make sure the comment line added in user_app1.c file is visible on your screen at the same time GitHub is. Right click where GitHub says “1 changed file.” Select the option “Discard all changes.”
The line of text written should disappear, and GitHub will be back to indicating “No local changes.”
Creating a New Branch and Committing Changes
GitHub probably created the “testing” branch a few steps above with the default of not bringing forward the changes you made. Change to this branch now in GitHub Desktop (if you do not have a “testing” branch, use Branch > New Branch to create one). Keep VS Code open on user_app1.c during these next steps.
In the comment line, add a note about the commit and click “Commit to testing”
Make sure you can see user_app1.c in VS Code. Change back to the “master” branch in GitHub Desktop. Notice that user_app1.c reverts back to its original form. If you change back to the “testing” branch, the changes made should reappear.
The last thing to try is pushing your local changes up to the cloud. Activate the “testing” branch and click “Publish branch” in the upper right or click the blue button.
Check the activity in your account on github.com to confirm. You should see the new branch available, as well as some sort of note about new changes and pull requests.
In a traditional branching model, you would likely merge in the changes of a branch to Master but in this case you don’t want to do that.
If all of this has worked, you have done everything you need for version control in EiE. As you work through the program, you will inevitably make some mistakes with the version control and end up writing to the wrong branch, having conflicts with your commits, deleting changes you wanted to keep, or generally tying yourself in a knot especially if you start working on a repo with another person. It’s always a good plan to copy your working Git folder to somewhere safe when you have a good working piece of code you don’t want to list. Even though you *should* be able to undo or redo any changes thanks to Git, there’s always ways to mess it up.
While there are many arguments in favor of various code control systems, no system is perfect. Git still relies heavily on the command-line interface for operations that are more than what can be easily used in the GUI. If you use Git regularly in industry, it’s recommended to take the time to really get to know the shell interface and your company’s version control model.
[LAST UPDATE: 2024-SEP-25]