Advanced version control

Cloning an existing repository

We’re not the first people to initialize repositories and use version control. In fact, vast online repositories of different projects exist on sites like GitHub, GitLab, SourceHut, and more.

Cloning an existing repository from a website is straightforward using the git clone subcommand.

git clone https://code.cs.umanitoba.ca/cs-lab-course/hello

Cloning into 'hello'...
remote: Enumerating objects: 8, done.
remote: Counting objects: 100% (8/8), done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 8 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (8/8), done.

Finding a repository’s address

Similar to connecting to a remote computer, we have to tell git where to find the repository by giving it an address or location. In the example above, I provided you with the complete command to clone the repository, but sometimes you’ll find a repository that you’re interested in cloning (including your own!).

Standard Ebooks is a web site that’s curated and published many free, high quality public domain e-books.

The team at Standard Ebooks use GitHub extensively to collaborate and track changes to the files that are used in the creation of their e-books. You can find a collection of their repositories on GitHub here:

https://github.com/standardebooks

Scroll down a little bit to the “Repositories” section and pick an e-book. The titles (unfortunately) are pretty messy here, but they are readable (if you can’t pick an e-book, I’ll pick one for you: Alice’s Adventures in Wonderland).

Once you click on a link to an e-book, you’ll be taken to the main page on GitHub for that repository. The main table in the center of the page is a listing of the files and folders that are in that repository. Just above and to the right of that table is a green button labelled “Code”:

Click the green “Code” button, then you can copy the text under “HTTPS”, this is the address of the repository that you’re going to use to tell git where it should look when it’s cloning the repository.

Now you can paste this link into your terminal as part of a git clone command:

git clone https://github.com/standardebooks/lewis-carroll_alices-adventures-in-wonderland_john-tenniel.git

Now you’ve cloned a repository! 🎉

Create a new remote version control repository

Cloning existing repositories is something that you will do sometimes, but not actually that often. The times when you will will want to clone existing repositories are either:

1. You’ve previously created a remote repository and you want to clone it into a new location, or
2. You’re downloading someone’s software for the purpose of compiling it and using it.

Let’s make our own new remote repository. Creating a new remote repository is different from initializing a repository on the command line with git init, but they are related to one another.

When you initialize a new repository on the command line, git is creating that .git directory that’s filled with all the stuff git needs to keep track of changes to your files. When you create a new remote repository, you’re really creating a well-known other place (that’s not on your computer or on Aviary) where you can duplicate and manage your files.

We’re going to be doing this not with GitHub, but with a free, open-source, and self-hostable product called GitLab. The U of M CS Department hosts an instance of GitLab (there’s a web site you can go to that’s dedicated for students taking COMP courses at the U of M) at

https://code.cs.umanitoba.ca

Open that link, then we’re going to go through a few things to create a new repository.

Sign up for GitLab

Before we can do anything with this instance of GitLab, you’re going to need to sign up for a new account. You can skip this step if you’ve previously signed up for a GitLab account here.

On the log in page, click on the “Register now” link, it’s just below the big blue “Sign in” button.

When you sign up, you can enter whatever you want for your “First name”, “Last name”, and “Username” (this is not audited by our tech staff), but you must use your @myumanitoba.ca e-mail address, no other e-mail addresses are permitted to sign up.

Just after you sign up, GitLab will ask you what you think your “role” should be. Ultimately this is helping GitLab decide how it should organize itself in terms of what you see when you first log in. I would suggest that you choose “Software Developer” here.

Congrats! You just signed up for a version control repository service! 🎉

Create a new repository

Now we get to the part that we’re really interested in: actually creating a remote repository to upload our code to.

Just after you finish creating your account, and each time you log in to GitLab, you’re going to be at your dashboard.

Click on “Create a project”. There are several options you can choose from to create a project, but for now you should click on “Create blank project”. Ultimately our goal is to copy an existing repository to this remote repository.

Now you get to be creative by picking a project name. The project name that you enter here will become part of the project’s URL (the address or location of the repository). If you’re following along with the examples from last week, you should pick something like my-project. If you want to start putting your course documents into this repository (like you might in an assignment), you should pick something like a course name (e.g., SCI2000).

The only option you have for visibility is “Private”, and you should leave it that way.

You’ll also see some options for project configuration. You should deselect everything for your first repository; we’re eventually going to be uploading an existing repository to this remote repository, and we don’t want any file conflicts.

Finally, click the “Create project” button. If everything’s worked out, you should see a new (and empty) project page:

You just created a new remote repository! 🎉

Pushing to a remote repository

Right, that repository is there, but it’s… empty.

Our goal now is to take an existing repository and “push” the repository’s contents to our new empty remote repository.

Open your terminal, connect to Aviary, and navigate to the folder that contains a git repository (one of the ones you created last week). Alternatively, create a new folder and initialize an entirely new repository, and add and commit some files to that repository. All of the examples below this section assume that your present working directory (pwd) is a Git repository and contains a .git folder.

Configuring your repository

Before you can push to a remote repository, you have to tell Git where it’s supposed to push to by configuring your repository. This is a one-time set up, you only need to do this once per repository.

You can configure the remote repository in Git using the git remote subcommand:

git remote add origin https://code.cs.umanitoba.ca/you/your-project

Pushing to the remote repository

Now that your repository has a remote, we want to push all the commits that you’ve made (and thus all the files) to the remote repository. Pushing to the remote repository is something that you should do often, our goal is to make sure that the local repository you have is approximately synchronized with the remote repository on the server.

You can push all commits to the remote repository using the git push subcommand:

git push -u origin main

git push

[you@bird my-project]> git push -u origin main
Username for 'https://code.cs.umanitoba.ca': you@myumanitoba.ca
Password for 'https://you@mumanitoba.ca@code.cs.umanitoba.ca':
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 225 bytes | 225.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To https://code.cs.umanitoba.ca/csstud1/my-project.git
 * [new branch]      main -> main
Branch 'main' set up to track remote branch 'main' from 'origin'. 

Branches

So far we’ve been using the basic features of Git to track changes to files that we have in a repository. We can visualize these changes as a linear list:

We can literally see this if we use the git log subcommand, and we can also get back to previous commits using the git checkout subcommand.

[you@bird my-project]> git log
commit 3d7739db044efa992bbfdb2d613a0fc025f39d71 (HEAD -> main, origin/main)
Author: Franklin Bristow <fbristow@cs.umanitoba.ca>
Date:   Mon Sep 26 14:07:53 2022 -0500

    Updating TODO.

commit 943ae855084a66fbdee8b7469f81be284e04cf65
Author: Franklin Bristow <fbristow@cs.umanitoba.ca>
Date:   Mon Sep 26 13:58:54 2022 -0500

   Writing more about version control.
    
   Looking back at log messages is cool, so let's use `git log` to see them. 

[you@bird my-project]> git checkout 3d7739

[you@bird my-project]> git switch main

This is good enough for the most part, but there’s more to Git than just keeping track of a linear sequence of changes over time. One of the most powerful concepts behind Git is that it can actually keep track of an entire graph of changes over time, possibly coming from many authors and contributors.

We’re going to take a look at a feature in Git called “branches”. Branches are something that we can use to track multiple independent sequences of commits to a repository simultaneously. When a repository has multiple branches, its commit history can look something like this:

Branches are very useful when you’re working in a team of people, who are each independently working on (for example) a feature in a bigger project. All of these people will want to independently make changes and commits, but not interfere with each other’s work until they’re finished.

Creating a new branch

You can create a new branch in your git repository using the git branch subcommand.

git branch my-new-branch

Listing and switching branches

We just created a branch (🎉), but… that’s not very useful in and of itself. We want to be able to see which branches are currently in a repository, and we want to be able to switch to that branch so that we can track changes. We’re going to use the git branch and git switch commands.

[you@bird my-project]> git branch
* main
  my-new-branch

[you@bird my-project]> git switch my-new-branch
[you@bird my-project]> git branch
  main
* my-new-branch

Once we’re on this new branch, we can use git the same way that we were before, adding and commiting changes, then switch back to our main branch using git switch.

Try creating several branches, make changes, stage (add), then commit those changes, then switch between branches to get an sense of how commits apply to branches.

Pushing branches to remote

You can also push branches that you have in your local repository to the remote repository. You actually already did this the first time you pushed to a remote repository with your main branch when you did git push -u origin main. You can also push local branches to remote with git push:

git push -u origin my-new-branch

Merging branches

OK great! Now we have one repository that has several different commit histories. If you want to think in terms of data structures (and maybe you don’t want to think in terms of data structures), we’ve effectively built a tree :tree: of commit histories.

Having these multiple, independent commit histories is fine, but if we’re working on a project with multiple people, and those multiple people each have their own branch, we need to be able to take all the work that they’ve independently done and put it back into the main branch so that we have a single project that has all the commits and features.

To do this, we’re going to have to “merge” the branches back together; take all the commits from one branch, and put them into another branch. We’re going to use the git merge subcommand to do this.

[you@bird my-project]> git branch
  main
  my-new-branch
* another-branch

[you@bird my-project]> git switch main # switch back to the main branch
[you@bird my-project]> git merge my-new-branch

Updating 8e7c6d6..ca7accf
Fast-forward
 updated-file | 3 +--
 1 file changed, 1 insertion(+), 2 deletion(-)

Merge conflicts

Things may not go smoothly. When two people are working independently on two different, independent histories within a single repository, they may need to make changes to the same file. git does a pretty good job of automatically “merging” multiple changes to the same file, but sometimes it can’t and you’ll get a “merge conflict”.

[you@bird my-project]> git switch main # switch back to the main branch
[you@bird my-project]> git merge my-other-new-branch

Auto-merging updated-file
CONFLICT (content): Merge conflict in updated-file
Automatic merge failed; fix conflicts and then commit the result.

[you@bird my-project]> git merge --abort

<<<<<<< HEAD
the content that's in the main branch
=======
the content that's in the branch you were trying to merge
>>>>>>> my-other-new-branch

[you@bird my-project]> git add .
[you@bird my-project]> git commit -m "Merge with my-other-new-branch"

Synchronizing projects between computers

Doing scp is, honestly, a little tedious. Even using graphical tools is pretty tedious.

One way (among many!) that you can keep your folders synchronized between two different computers is to use a remote git repository, cloning and pulling on the “secondary” computer (Aviary in this case).

You’ve already got your repository on Aviary, so let’s clone the repository onto your own personal computer.

Install Git

Git is originally a command-line tool (how you’ve been using it). You can install git on all of Windows, macOS, and Linux. How you install it depends on which of those that you’re using.

Cloning your repository

Once you’ve got a git client installed you can actually follow the instructions in Cloning an existing repository.

Workflow

You can generally keep using git the way that you’ve been using it up until now: make changes to your files, stage the changes with add, then commit the changes to history.

Now you should also push to your remote repository occasionally:

[you@bird my-project]> git push

You don’t need to do -u origin.

To get the changes on your other computer, you should use git pull:

[you@your-computer my-project]> git pull

Depending on what you’ve done with your repositories, you may get merge conflicts when you pull (if you edited a file on your local computer and on Aviary). You can deal with merge conflicts as described above.

Further reading

This is a lot.

Git is an incredibly big tool with lots of ways to use it, and we couldn’t possibly look at every possible way to use it.

Instead, here are some additional resources for using Git that you can check out:

• The Documentation page on Git’s homepage. This actually has several sub-resources that you should check out: a complete reference manual for Git, “Pro Git” (a book), and a series of videos introducing basic Git.
• Learn GitLab with tutorials is a pretty comprehensive overview of GitLab itself. There’s a lot about Git in this set of tutorials, but the target for these tutorials is specifically how to use GitLab. Some of the skills that you learn here would be transferable to something like GitHub.
• Learn Enough Git to be Dangerous is a good resource for version control basics. Part of it is free, but it isn’t entirely free.
• GitHub Skills is a suite of resources similar to “Learn GitLab with tutorials”, but targeting GitHub specifically.