Source Control with Git

Currently, our Git repository and history are stored only on our machine. To share our code and collaborate with others, it needs to be stored somewhere they can access it. This is the job of a remote repository.

Most teams use third-party services like GitHub, GitLab, or Bitbucket for hosting their remote repositories. For this course, we'll use GitHub, the most popular choice.

Authenticating with GitHub

After creating a free GitHub account, you need to authenticate your computer or development environment with your GitHub profile.

This means that, when your computer attempts to upload code, GitHub can verify that the request is coming from you.

The typical way of setting this up is to create and upload an SSH key to your profile. The GitHub documentation walks you through the process.

Pushing Code

Once our account is set up and authenticated, we can create the remote version of our repository by completing the form at https://github.com/new

Once it's created, GitHub will provide you with a URL for your new repository (e.g., https://github.com/Username/Greeter.git).

We need to "link" our local repository to this remote repository. Most services, including GitHub, will provide the exact command for this after you create the repository on their site. It will be something like this:

1git remote add origin git@github.com:username/Greeter.git

It's possible for a single local repository to have multiple remote repositories so, to tell them apart, we are required to name our remotes.

Most projects have only a single remote, and the universal convention is to call this remote origin. This is what we did in the previous command.

Pushing Code

With the remote configured, we can upload (or "push") our local commits to GitHub using the git push command. Before pushing our changes, GitHub also recommends renaming our branch from the default name of "master" to "main", and our repository page provides the command to do this:

1git branch -M main

We cover branches in more detail later. For now, after renaming our branch, we can push our code for the first time. GitHub also provides the command for this in our repository page:

1git push -u origin main

The first time we push, we use the -u flag to tell Git to link your local main branch with the main branch on the origin remote.

If everything is set up and authenticated correctly, we should get confirmation that our changes have been pushed:

1Enumerating objects: 15, done.
2Counting objects: 100%, done.
3Compressing objects: 100%, done.
4Writing objects: 100%, done.
5To https://github.com/Username/Greeter.git
6 * [new branch]      main -> main
7Branch 'main' set up to track remote branch 'main' from 'origin'.

If you now refresh your repository's page on GitHub, you'll see all your code has been uploaded and is available to anyone with access to your repository.

One of Git's most important features is branching. A branch is an independent line of development. When you want to work on a new feature or fix a bug, you create a new branch. This allows each developer to make commits and experiment in isolation in their own branches, without affecting anyone else on the team.

For example, one developer might be working on some new feature, whilst another developer can work on fixing some broken tests:

Once their work is complete and tested, they can merge it back into main. The simplest form of this involves creating a new "merge commit" on the destination branch:

Git can almost always automate this merging process for us, creating a merge commit that will apply all of the changes we made in our source branch to the destination branch.

Situations where this cannot be automated are called merge conflicts. This would happen if, for example, we updated a line of code in our branch, and the branch we're trying to merge to deleted that same line. Git doesn't know what the resulting code should look like in such scenarios, so it will ask us to manually intervene.

We cover this merging process later in the lesson.

Creating Branches

As we've seen, the default branch is usually named main or master.

Let's create a new branch to work on our next feature. In this case, we'll use GoogleTest to add a new test.

To create a new branch, we use git checkout -b command, passing a name for our branch:

1git checkout -b improve-tests

1Switched to a new branch 'improve-tests'

This both creates a new branch, and "checks it out". Any commits we make are to the branch we currently have checked out. We can find out which branch that is by using git status again:

1git status

1On branch improve-tests
2nothing to commit, working tree clean

Commiting to our Branch

In our previous lesson, we updated our Greeter library to return an empty string if the user's name was "Bob".

We didn't add a test for this change, so let's do that now. With our parameterized testing setup, we can add this test with a single line of code:

1#include <gtest/gtest.h>
2#include <greeter/Greeter.h>
3#include <tuple>
4
5class GreeterNameTest :
6  public testing::TestWithParam<
7    std::tuple<std::string, std::string>
8  > {};
9
10TEST_P(GreeterNameTest, GreetsCorrectlyForName) {
11  auto [name, expected_greeting] = GetParam();
12  Greeter greeter = name.empty() ? Greeter() : Greeter(name);
13  EXPECT_EQ(greeter.greet(), expected_greeting);
14}
15
16INSTANTIATE_TEST_SUITE_P(
17  NamedGreetings,
18  GreeterNameTest,
19  testing::Values(
20    std::make_tuple("", "Hello, User!"),
21    std::make_tuple("John", "Hello, John!"),
22    std::make_tuple("Jane", "Hello, Jane!"),
23    std::make_tuple("Bob", "")
24  )
25);

If we save our file, Git should notice the change, but it hasn't yet been staged for commit:

1git status

1On branch improve-tests
2
3Changes not staged for commit:
4        modified:   tests/greeter/test_greeter.cpp

We can stage our changes and create a commit as before:

1git add .

1git commit -m "Add test to ensure Bob is ignored"

We can push this new branch to the remote repository, just as we did before:

1git push origin improve-tests

If we now visit our repository on GitHub, we should see both branches saved to our remote:

In most teams, you are not allowed to push your changes directly to the main branch. This branch is usually assigned particular importance. Since all new feature development begins by branching off from main, we want to keep that trunk in a stable and high-quality state.

To enforce this, repository administrators will configure main as a protected branch. This blocks direct pushes and forces all changes that will affect this branch to go through a formal process.

These restrictions are set up on the remote repository. On GitHub, for example, these rules are set up in the Settings > Rules page for the repository.

Pull Requests

The formal review process of getting changes into an important, protected branch is a pull request (or "merge request" on platforms like GitLab). A pull request (PR) is a proposal to merge the changes from one branch (usually the branch you made for your specific feature) into another branch (usually a protected branch like main).

Once we've pushed the changes in our branch, it should show up on the Branches list in our GitHub repository and, from there, we can create a pull request to merge the changes of that branch into some other branch, such as main.

Once we create a PR, it will be available on GitHub's UI. This lets us create a title and description for our request, whilst GitHub will automatically show all of the changes that are in our branch. Our colleagues will visit this page, review and approve our changes, ask questions, or make suggestions on what could be improved.

When our changes are approved, a button to merge our pull request becomes available, which will integrate our changes into the target branch, such as main:

For a pull request to be approved and merged, most teams require two forms of checks:

1. Manual Checks: One or more of our colleagues need to check our proposed changes and approve them.
2. Automated Checks: Some checks can be automated. For example, when a PR is opened, we can set up a script that downloads the code in the branch, compiles it, and ensures all the automated tests pass.

Setting up automated checks will be the focus of our next lesson. For now, we can just merge our changes on our remote, using the Merge pull request button.

With our changed merged into our main branch, we usually no longer need the branch we created for this feature. After the merge is complete, GitHub's UI gives us a button to delete the branch in our remote repository.

We can also delete the branch in our local environment if we want. First, though, we should switch back to using the main branch locally. We can do that using the checkout command:

1git checkout main

1Switched to branch 'main'

We can then delete our previous branch, if we want:

1git branch -D improve-tests

1Deleted branch improve-tests (was c8e88c3).

On our remote repository, the main branch has now been updated with the changes that were merged in through the pull request.

This means that our local repository is out of date, as we haven't downloaded and integrated those changes yet. We can check this using the git status command:

1git status

1On branch main
2Your branch is behind 'origin/main' by 2 commits.
3  (use "git pull" to update your local branch)

As the output suggests, we can pull the latest changes into our local repository using git pull, which will get everything back in sync:

1git pull

The output will confirm that the changes have been downloaded successfully, and which of our local file(s) have been updated with the incoming changes:

1Updating f36aa31..1247998
2 tests/greeter/test_greeter.cpp | 16 ++++------------
3 1 file changed, 4 insertions(+), 12 deletions(-)

Working on the Next Feature

From there, we simply repeat the process. We create a new branch for our next feature or improvement:

1git checkout -b some-new-feature

We implement the changes in our code editor, making commits as we reach key steps in the process:

1git add .

1git commit -m "Added the basic structure"

When we're done and want to create a PR, or when we want to back up our progress to the remote in case something goes wrong with our computer, we push our branch:

1git push origin some-new-feature

And finally, we navigate to our repository on GitHub and open a pull request through the UI

In this lesson, we covered the Git fundamentals that are useful for collaborating on projects.

• Repository: A project's history is stored in a Git repository, initialized with git init.
• The Commit Cycle: You stage changes with git add ., save them as a snapshot with git commit -m "message", and upload them to a remote server with git push.
• Ignoring Files: The .gitignore file is used to keep your repository clean of generated files and local configuration.
• Branching: Branches (git checkout -b ...) allow for parallel development, enabling you to work on new features without destabilizing the main codebase.
• The PR Workflow: Protected branches and pull requests are the standard mechanism for ensuring code quality and triggering automated builds before changes are merged into the main line of development.