1 About git and gitlab

git is the standard tool that software developers use to work on coding projects together. In this class, you will be working in pairs for most of the labs and for the project, so it makes sense for us to use this tool so you collaborate. As a bonus, you will gain more familiarity with this industry-standard and useful tool.

GitLab is a web service that provides an easy way to host and share git repositories. It has a similar set of functions to github which you may have heard of, but the advantage of being open-source so that we can run our own GitLab server at USNA. For free. Neato!

One of the best features of git is that it frees you from the anxiety of losing your work. The point of using a tool like git is to help track all of the changes in your source code files as you work, and to "merge" together different versions if, say, your lab partner fixes a bug in one part of the code while you're simultaneously forging ahead on another part.

If you use git in a reasonable way, it becomes impossible to lose your work because it's all saved in the repository. However, it can definitely become difficult to sometimes decipher what's happening when things go wrong. So, if in doubt, don't hesitate to ask your instructor for help!

2 Initial setup

2.1 GitLab account

Go to gitlab.usna.edu (intranet only) and:

1. Create an account if you don't already have one. If you have one, log in and go to your profile settings.
2. Make sure your full name is listed (like how it appears in emails).
3. Check the box to share your email address publicly.

2.2 Computer setup

Repeat these steps on any computer of VM where you want to access your GitLab repositories:

1. Check if you already have an ssh key generated:

   ls ~/.ssh/id_ed25519.pub

2. If not, then make one:

   ssh-keygen -t ed25519

3. Now take a look at your public key (it should be just one line):

   cat ~/.ssh/id_ed25519.pub

4. Login to gitlab.usna.edu
5. Under your user icon (top-right), go to Preferences
6. Select SSH Keys on the left panel
7. Paste that entire line (from step 3) into the box and click Add Key

2.3 Cloning a repo

Git is a distributed version control system, which means that a full copy of your source code repository exists on the GitLab server, but also on any computer or VM where you want to work with your code.

In git terminology, cloning means creating a new copy of a repository by copying it from another computer, and making that initial connection. Usually, you will clone from the GitHub server to a computer only once (after the initial clone, you are just updating the existing local copy of the repo).

1. Open a terminal on the computer where you want a copy of the repo (for example, your VM)
2. Navigate (cd) to the parent directory of where you want the repo to live. For example, if you want the repo to live in ~/goatcoin, you can just cd ~.
3. Run this command to clone, of course replacing with your own alpha:

   git clone gitlab.usna.edu:m123456/goatcoin

   That creates a new directory goatcoin (or whatever your repo is named) and syncs it with the version on the gitlab server.

3 Working with git

Git is a tool to keep track of different versions of your files as you work, and to sync up that work between different computers or different programmers. For example, your instructor uses git to store the source code for this very website, and to keep track of changes when he's working from home, or the office, or the actual "live" version that you see online. For this class, you will use your git repo (at least) to share your code with your instructor, and to keep track of versions as you make incremental progress in each week's lab.

It's important to remember with git that you have a "local copy", which is the files you're dealing with on your own computer or VM, and a "remote copy", generally stored on GitLab or GitHub. It's important to know what commands affect the local copy, and which ones interact or sync up the local and remote versions.

A little git advice: (1) Don't panic; ask for help if needed. (2) Thousands and thousands of programmers use git every day. Use the internet to help you learn. (3) Read the output on your screen! When you run a command, git will tell you what is happening and suggest what to do when something goes wrong.

3.1 Most important commands

Here is a brief summary of the most important commands. For detailed documentation on any one of them, just run e.g.

git help push

Some typical ways these commands are used are outlined in the subsections below.

Command	Brief description	Read/write local?	Read/write remote?
git status	Tells you whether your files are up to date, or if you have unsaved changes that should be committed	read
git pull	Gets changes from the server and applies them to your local version	write	read
git add FILENAME	Tells git to keep track of a new file or files	write
git commit -a -m MESSAGE	Saves current state of all files in a single "commit"	write
git tag TAGNAME	Applies a tag on the most recent (previous) commit	write
git push --tags	Copy any changes (commits and tags) from the local side to the remote server	read	write

3.2 Typical workflow

Here's what a coding session might typically look like with git

First, navigate to your git directory and check the status

roche@ubuntu$ cd goatcoin
roche@ubuntu$ git status
On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

That status message means you're all good and ready to go. If instead you see:

• "Untracked files": you might need to do a git add to tell git to track those files. (If you know the file is not important, you can ignore this message or add to your .gitignore file.)
• "Changes not staged for commit": You've changed some files but still need to do a git commit -a. Do it now!
• "Changes to be committed": You've added some files, but still need to do a git commit Do it now!

Once your status is clean, update your local version from the server:

git pull

Typically, the response will be "Already up to date". Otherwise, you will see a summary of what files got updated.

Now, do some work. You can just treat this directory and files like any other; go for it!

After you've made some progress, and certainly before you log out or start doing something else, save your work. If you've made any new files, do git add FILENAME to tell git to track them. Then run

git commit -a -m "some message about what you did"
git push

to gather up all your changes and push them to the server.

If you need to create a tag (like when you are done with a major milestone), you can do this after calling git commit:

git tag YOUR_TAG_NAME_NO_SPACES
git push --tags

Then go back to step 1! That's really it.

3.3 Slightly more advanced

If you want to explore further, here are just a couple more git things that I find very useful:

• Branches: You can have multiple parallel versions of your code and jump between them, occasionally picking changes from one and putting it somewhere else. For example, it's very common to have a "main" branch which is kept always working correctly, and a "devel" branch where you are actually making changes and sometimes breaking things.
  Branches are really powerful but take a little getting used to. Different people have different "taste" in how you should organize your project with regard to branches. For small projects, you can probably do very well with just "main" and "devel".
• gitignore: These are special files you can put anywhere in your git directories that tell git to ignore certain files and never try to add them to the repo. That's really useful for things you don't really need to keep synched, like compiled binaries, .class files, __pycache__ directories, etc.
• git fetch and git merge: Technically, running git pull does a fetch first and then a merge. For simple cases you usually want to do both at the same time, but sometimes (especially when dealing with branches), it's nice to keep the "download" part (fetch) separate from the "combine with my current files" part (merge).