Gitlab Guide

One of the key software tools covered in CSE 374 is version control software. For hw6 you will use Gitlab and git to store the project code and share it with your partner. This guide will help you get started with Gitlab and has some suggestoins on how to use Git effectively.

Gitlab Setup
Git Workflow

CSE 374 Gitlab Setup

These instructions are for connecting your CSE Linux environment (cancun or VM) to your GitLab repo in preparation for hw6. A gitlab repository will be created for each pair of students working together on hw6, and you and your partner will use it to store the code for that assignment. The following section has more tips and tricks for using git as you work on your hw.

Find Your 374 Repository

Once gitlab repositories have been created, navigate to https://gitlab.cs.washington.edu
- Most CSE 374 students should use the "UW NetID" button, but if you have a CSENetID, use the "CSE NetID" button instead.
In your list of Projects, you should see a CSE374 repo named cse374-22sp-students/cse374-22sp-<xx> created for you already (where <xx> is the two-letter group id assigned to you and your partner).
- This repo will be created from the information about you and your partner submitted on the hw6 partner info form. If you do not see yours once repos have been created, 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 and sometimes makes it almost unusable.

Check to see if your CSE Linux environment (cancun 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. This is unlikely to be the case for most CSE 374 students.
Generate a new SSH key by running:
```
ssh-keygen -t rsa -C "<netid>@uw.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 Default Options

For the most part, git has sensible default options and things work as expected. However, if you've never used git before, it will ask / remind you to set some options every time you try to commit or push something. Before starting to work with gitlab regularly, we suggest you enter these commands in a terminal window.

     git config --global user.name "Your Name Here"
     git config --global user.email netid@uw.edu
     git config --global pull.rebase false

Of course you should substitute your own name and email in these commands. This only needs to be done once and the settings will be retained and used as defaults in the future.

Your First Commit

Any commands shown below should be run from your CSE Linux environment (cancun 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 one 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 (cancun 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):

[cancun]$ 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. You should always do a git pull before adding or committing any new files or changes to your local copy of the repository.

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!

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

```
[cancun]$ 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.

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

[cancun]$ 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 374 we generally 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 getting necessary files pushed to the repositories.

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 374 gitlab repo. While these are widely used in large projects and in industry, they are not needed for CSE 374 (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.

Be Skeptical About Web Searches

Git, github, and gitlab have enormous user bases and are used for a huge variety of projects. They also have many, many, many features and options and are very complex. Because of that, web searches about git can produce a huge number of potentially off-topic or inapplicable results and, if blindly followed, can leave your repo in strange and potentially very hard to fix states. If you are having problems with your gitlab repo, please contact course staff so we can help you fix things. We deliberately are not taking advantage of many git features to keep things simple and understandable for what we need for this class.

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" homework 6 requires you to add tags to commits in your Gitlab repository in order for the staff to evaluate your homework. The code will eventually be uploaded by the course staff to gradescope to make the feedback available, but we will get the code directly from your gitlab repo and you will not upload it to gradescope yourself. Here are some reminders on how to tag your Gitlab repository (repeated from hw6).

Adding a Tag

Be sure to add a tag after you have completed the assignment. What the tag does is it marks a specific commit in your Git repository as the one to be evaluated

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

Removing an Old Tag

If you need to make changes to an assignment after previously adding a tag, be sure to remove the old tag with the commands below and add then add a new tag after you have committed and pushed the changes.

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