Gitlab Guide

Throughout CSE 333, you will use Gitlab and git control flow to work on the project homework assignments. This guide will help you get started with Gitlab and discuss how to use Git effectively.

Gitlab Setup
Git Workflow

CSE 333 Gitlab Setup

These instructions are for connecting your CSE Linux environment (attu, lab workstation, or VM) to your GitLab repo in preparation for hw0 – hw4. The following section has more tips and tricks for using git as you work on your hw.

Find Your 333 Repository

Navigate to https://gitlab.cs.washington.edu
- If you have a CSENetID, use the "CSE NetID" button; otherwise, use the "UW NetID" button
In your list of Projects, you should see a CSE333 repo named cse333-22au-students/cse333-22au-<netid> created for you already (where <netid> is your UW netid).
- These are usually created during the first week of the quarter when the hw0 project is released. If you do not see your repo after that is announced, please contact the course staff (private posting on Ed) as soon as possible so we can fix the problem.

Add Your SSH Key

This will allow you to access your repo without having to authenticate (i.e., type your password) every time and will greatly improve your workflow. You should do this since password authentication can be awkward at best for routine gitlab use.

Check to see if your CSE Linux environment (attu, lab workstation, or VM) account already has an SSH key by running:
```
cat ~/.ssh/id_rsa.pub
```
- If you see a long string starting with ssh-rsa or ssh-dsa, skip to Step 3.

Generate a new SSH key by running:

ssh-keygen -t rsa -C "<netid>@cs.washington.edu"

Print your SSH key to the terminal by running:
```
cat ~/.ssh/id_rsa.pub
```
Highlight and copy the complete key (i.e., starting with ssh- and ending with your username and host)

Add your SSH key to GitLab
- Navigate to your SSH Keys page by clicking on your avatar in the upper-right, then "Preferences", then "SSH Keys" in the left-side menu.
- Paste your SSH key from Step 4 into the "Key" text box and give a "Title" to idenfity what machine the key is for.
- Click the "Add key" button below "Title".

Set Git options

Git uses a .gitconfig file in your home directory to store options that you have configured. We suggest that you don't include much here since the defaults are generally what you want and changing defaults can lead to confusing or unexpected behavior. However there are three options that you should set so that git will not pester you with warnings every time you try to commit or push changes. You should enter the following commands once before you start using git/gitlab:

     git config --global user.name "Your Name"
     git config --global user.email username@cs.washington.edu
     git config --global push.default simple

Substitute your own name and email address, of course. If you use git on more than one machine, you will need to do this once on each machine.

Your First Commit

Any commands shown below should be run from your CSE Linux environment (attu, lab workstation, or VM).

Find your repo's URL by navigating to your project's details page, clicking the blue "Clone" button on the right, and then clicking the copy icon under "Clone with SSH".
```
git clone <repo url>
```
```
touch README.md
```
- This creates an empty file called README.md.
```
git status
```
- This prints out the status of the repo – you should see 1 new file named README.md.
```
git add README.md
```
- Stages a new file/updated file for commit. This time, it should output git status: README.md staged for commit
```
git commit -m "First Commit"
```
- Commits all staged files with the provided comment/message. This time, it should output git status: Your branch is ahead by 1 commit
```
git push
```
- Publishes the changes to the central repo, which should now be viewable in the web interface. You may need to refresh your browser first.

Developing with Git Workflow

Once you have a made a local copy of your Gitlab repository in your CSE Linux environment (attu, lab workstation, or VM), you can now have access to and make changes to files your repository locally! However, note that the repository on Gitlab and the copy in your CSE environment do not automatically synchronize with each other, so you have an additional responsibility of keeping both of them up to date (so you don't have out-of-date copies in either place or lose work if something goes wrong with your local copy of the repo).

Updating Local and Gitlab Repositories
Methods in recovering weird Git situations
Managing Homework Tags

We recommend you use the git workflow described here. (If you are interested in more details, the Git Community Book is a great resource as well).

Updating Local and Gitlab Repositories

To update your local copy of the repository with any new information in the Gitlab copy of the repository, type the following command (in your local repository):

[attu]$ git pull

You may run into a merge conflict when working with other collaborators, or if the course staff has added new files to the repository. Refer to GitHub Docs for resolving merge conflicts. You can reduce the possibility for merge conflicts by consistently making sure your repository is up to date when developing.

Commit and add changes from your local copy to the Gitlab repository:

Make sure that all files are saved in your local copy first and you are in your local copy of the repository!

[attu]$ git pull  # make sure your local copy is up to date with Gitlab

```
[attu]$ git add <files> # stages files to commit to Gitlab
```
- You may want to use . (period character) in <files> from the top-level git repository directory to stage all files to be added to Gitlab repository. (Note: . represents current directory, so at top-level of the repository, you are adding and staging all changes in local copy of the repository!)
- You should not include files in git add that you do not want to commit to the Gitlab repository

[attu]$ git commit -m “<message here>” # add a descriptive message about your update

[attu]$ git push # push your changes to your Gitlab

You should only commit source files since everything else just takes up unnecessary space in your repo and can be (re)built from the source files. Compilation products also become stale (i.e., out of date) as soon as you make any changes to your source files, and having obsolete copies in your gitlab repository can create potential confusion. We have included in your starting repository a .gitignore file that list files and file types that will be ignored when updating the Gitlab repository. This may be particularly useful for not including executables or object files (.o files), which is already done for you. You can add more files that you may not want to include in .gitignore. However, for CSE 333 we strongly recommend that you do not make changes to the distributed .gitignore file, since some changes that might seem useful have been known in the past to interfere with distribution of binary files that need to be included with homework project starter code.

Recovering from Weird Git Situations

Keeping your workspace organized is crucial to keeping your workflow smooth, efficient, and as productive as it can be. By making sure to frequently update your local and Gitlab repository, you reduce the chances of getting into trouble. Nevertheless, you might end up with a “Git spaghetti ball,” so here are some useful survival tips and commands.

Keep it simple

Avoid branching, merging, and other complex git structures in your CSE 333 gitlab repo. While these are widely used in large projects and in industry, they are not needed for CSE 333 (our project structure is not that complex). When not used correctly, these can leave your repo in an unexpected state where new changes seem to disappear or other odd things happen. Keep it simple.

Recovery from Messiness Locally

These git commands are ways to manage local changes to your git repository before pushing to your Gitlab repository.

Hide changes and gives you a clean working directory without having to commit a meaningless snapshot in order to save the current state.

git stash

Revisit your previous changes after you're done working on a fix.
```
git stash pop
```
Clear the stash stack of any changes you no longer need.
```
git stash drop
```
Reset your files to the HEAD of the branch if you don't want your changes anymore.
```
git reset --hard HEAD
```
Reset a single file isntead of the entire branch.
```
git checkout HEAD -- path/to/file
```
Revert changes that were already committed.
```
git reset --soft HEAD~1
```

Managing Git Tags

Turning in your homeworks (not the exercises!) requires you to add a tag to a commit in your Gitlab repository in order for the staff to grade your homework. As a reminder, you will not turn in your homework projects through gradescope. Here are some instructions on how to tag your Gitlab repository (repeated from hw0).

Adding a Tag

Make sure to add a tag after you have completed the homework. What the tag does is it marks a specific commit in your Git repository for a person to look at (what the files look like at that time of commit)

[attu]$ git tag hw<hw_num>-final
[attu]$ git push --tags

Removing an Old Tag

If you add or commit changes to the homework after adding a tag, make sure to remove the old tag with the lines of code below and add then add a new tag afterwards.

[attu]$ git tag -d hw<hw_num>-final
[attu]$ git push origin :refs/tags/hw<hw_num>-final