Git Version Control Primer

Git Logo by Jason Long is licensed under the Creative Commons Attribution 3.0 Unported License

The AppliedLogix team primarily uses the Git distributed version control system (DVCS) to track and manage software, firmware and FPGA source code. We regularly provide direct Git repository access to clients. We have standardized on Git because it is a contemporary, industry-standard, cross-platform, widely-supported system that has the flexibility to manage complex, professional-grade projects. If your software development team is not currently using a version control system, we strongly advise adopting one, and (naturally) recommend considering Git.

This primer provides background information about the Git system, our usage patterns and practices, and our Git support infrastructure. If you are an AppliedLogix client in need of direct repository access to your source code, please contact your program manager or lead software developer.

Git Basics

Git is a distributed version control system. In general, software developers use version control systems to keep track of the changes they make to source code over time. Git’s core mission is to keep track of what changes developers make, which developer made them, and why (via brief notes and messages). As multiple developers contribute code to a software, firmware or FPGA project, Git helps them keep their source code up-to-date, and merge in changes from others.

Git stores source code in project repositories. Generally, each project has a single repository, though some shared-code libraries may have their own repositories. Being a distributed version control system, Git efficiently stores the complete history of each repository on every participating developer’s computer, providing redundancy. Developers may also utilize a central repository (often on a shared file server) to coordinate changes and serve as a “master” copy of the software.

The following resources provide additional basic information about Git:

Repository Hosting

AppliedLogix hosts all company and client Git repositories at RepositoryHosting.com, which provides a private repository environment built on Amazon’s distributed EC2 infrastructure. We create accounts on this service for client personnel interested in interacting directly with project repositories hosted there. Alternately, clients may provide their own central hosted Git repositories, granting access to AppliedLogix personnel for code pushes.

SSH access to Git repositories hosted at RepositoryHosting.com take the general form:

ssh://git@appliedlogix.repositoryhosting.com/appliedlogix/client-project-name.git

In order to clone, push or pull from repositories on RepositoryHosting, you’ll need to generate an SSH key (generally using ssh-keygen on your development computer) and add the key to your RepositoryHosting account. RepositoryHosting provides detailed instructions on how to generate your key and add it to your account, and your AppliedLogix software team members can also help with this one-time process.

Git Clients

Ready-made Git clients for Windows, Mac OS X and the various flavors of Linux and Unix are readily available via package managers and the Git website’s downloads area at https://www.git-scm.com/downloads

While most developers interact with Git via the console or command-line, various graphical Git clients exist. The AppliedLogix team recommends TortoiseGit, as well as the Git client built into the Eclipse IDE.

Branching, Merging, Tagging and Git Flow

The Git DVCS provides powerful branching/merging capabilities. Adopting the metaphor of a tree that represents variation in source code over time, branches allow code changes to be made in isolation, then merged back together into the tree’s “trunk”. While merging branches can be a major headache with legacy version control systems, Git largely automates the process. As a result, branching and merging become a routine part of development workflows based on Git.

Despite its powerful branching/merging capabilities, Git imposes few requirements on the use of branches. Projects with multiple branches can easily get out-of-control or become difficult to manage. To prevent this, the AppliedLogix software team uses the Git Flow branching methodology, which imposes a layer of discipline on top of Git’s free-form branch/merge system.

Git Flow provides a standard set of branches to which developers commit code changes. Mainline development and integration takes place on the “develop” branch, while individual functions are implemented on “feature” branches, such as feature/555-timer-driver. Releases are prepared on “release” branches, such as release/1.0-prototype, and are tagged and merged to the repository’s “master” branch. As such, the tip of the “master” branch always represents the most-recently-released version of the software, while the tip of the “develop” branch always represents the most-recent ongoing development state. Release tags permit the quick recall of individual releases.

The Git Flow methodology can be followed manually, by issuing commands as prescribed at the background link above. Alternately, a set of open-source Git Flow scripts is available to automate the branching/merging steps involved in starting and finishing features and releases. While these scripts are not actively maintained, they are based on well-established Git commands and work well even on recent versions of Git.

The AppliedLogix software team also regularly creates Git tags for smaller development milestones that do not result in releases, such as demonstration builds or snapshots sent to clients. Just like branches, tags can be pushed to the central shared Git repository.

AppliedLogix repositories utilizing the Git Flow methodology generally contain a “GIT-FLOW.txt” or similar README file at their root, containing background information and instructions for use. If this file is absent, you can also identify a Git-Flow-managed repository by the presence of a develop branch.

Git Submodules

Many AppliedLogix Git repositories utilize Git’s submodules feature, which allows embedding of one Git repository within another, while maintaining separate commit histories. The AppliedLogix software team frequently uses the submodule feature to incorporate shared code libraries within client projects.

For example, we might include our common, re-usable CAN data formatting library in a project. The CAN library lives in its own Git repository, and has its own commit history. We can incorporate the CAN library into multiple “parent” project- or client-specific repositories using a git submodule. In these instances, the parent Git repository simply maintains a “pointer” to a specific commit in the child repository.

Detailed information about Git submodules and how to use them is available at:

AppliedLogix repositories utilizing submodules generally contain a “SUBMODULES.txt” or similar README file at their root, containing background information and instructions for use. If this file is absent, you can also identify a repository that contains submodules by the presence of a .gitmodules file at the root of the repository.


Git Logo by Jason Long is licensed under the Creative Commons Attribution 3.0 Unported License