Git Guidance — CS 330e Elements of Software Engineering I

Resource Pages

Start Here

Set up UTCS access, Python, Git, coverage, and required tools.

Git Guidance

Configure Git, connect securely to GitLab using SSH, and practice common repository workflows.

Unix/Linux Commands

Searchable command reference for working in the shell.

Overview

Git is a version-control system that tracks changes to files and helps developers collaborate. GitLab is a website that hosts remote Git repositories.

In this course, you will normally interact with GitLab using SSH. SSH allows your computer to authenticate with GitLab using a key instead of repeatedly entering credentials.

On macOS, use Terminal. On Windows, use Git Bash for the commands on this page.

The $ shown in command examples represents the terminal prompt. Do not type the $.

Part 1 — One-Time Git and GitLab Setup

Complete this section once on each computer that you will use for course work.

Configure your Git identity
Replace John Galt and jgalt@example.com with your own name and email.

Use the same email address that is registered and verified in your GitLab account. This helps GitLab correctly associate your commits with your account.
```
$ git config --global user.name "John Galt"
$ git config --global user.email "jgalt@example.com"
$ git config --global push.default simple
$ git config --global color.ui true
$ git config --global init.defaultBranch main
```
If you are using macOS:
```
$ git config --global core.autocrlf input
```
If you are using Windows with Git Bash:
```
$ git config --global core.autocrlf true
```

Check your Git configuration

$ git config --list

You should see entries similar to:

user.name=John Galt
user.email=jgalt@example.com
push.default=simple
color.ui=true
init.defaultbranch=main
...

Check whether you already have an SSH key
SSH keys are stored in the ~/.ssh directory. Run:
```
$ ls -al ~/.ssh
```
Look for the following two files:
```
id_ed25519
id_ed25519.pub
```
If both files exist, you probably already have an SSH key and can continue to the step where you add the public key to GitLab.

If they do not exist, generate a new key in the next step.
Generate an SSH key
The following command works in both macOS Terminal and Windows Git Bash:
```
$ ssh-keygen -t ed25519 -C "your_email@example.com"
```
Replace the email address with the email associated with your GitLab account.

When you see a prompt similar to:
```
Enter file in which to save the key (.../.ssh/id_ed25519):
```
press Enter to accept the default location.

You will then be asked for a passphrase. You may create one for additional security.

After the command completes, verify that the files were created:
```
$ ls -al ~/.ssh
```
You should now see:
```
id_ed25519
id_ed25519.pub
```
Important:
id_ed25519 is your private key. Never share it or upload it to GitLab.

id_ed25519.pub is your public key. This is the key that you add to GitLab.
Copy your public SSH key
You can display the public key on either macOS or Windows:
```
$ cat ~/.ssh/id_ed25519.pub
```
Copy the entire line. It should begin with ssh-ed25519.

You can also copy it directly to the clipboard.

macOS Terminal:
```
$ pbcopy < ~/.ssh/id_ed25519.pub
```
Windows Git Bash:
```
$ cat ~/.ssh/id_ed25519.pub | clip
```
Add your SSH public key to GitLab
1. Log in to your GitLab account.
2. Select your avatar in the upper-right corner.
3. Select Edit profile.
4. Select Access > SSH keys.
5. Select Add new key.
6. Paste the contents of id_ed25519.pub into the Key field.
7. Give the key a descriptive title, such as My Laptop.
8. Select Add key.
Test your SSH connection to GitLab
Run:
```
$ ssh -T git@gitlab.com
```
The first time you connect, SSH may ask whether you trust the GitLab host. Verify the host information and accept it when appropriate.

If the connection succeeds, GitLab should display a welcome message containing your GitLab username.

SSH setup is normally done only once per computer.
After it is configured, the same key can be used with the GitLab repositories that your GitLab account has permission to access.

Part 2 — Creating and Cloning a Repository

Create a repository on GitLab
1. Log in to GitLab.
2. Select New project/repository.
3. Select Create blank project.
4. Choose a project name, such as my-repo.
5. Select the visibility level required by your assignment.
6. Select Initialize repository with a README.
7. Select Create project.
Clone the repository using SSH
On your GitLab project's page:
1. Select Code.
2. Find Clone with SSH.
3. Copy the SSH URL.
The URL should look similar to:
```
git@gitlab.com:jgalt/my-repo.git
```
In Terminal or Git Bash, move to the directory where you want to store your repositories and run:
```
$ git clone git@gitlab.com:jgalt/my-repo.git
```
Then enter the repository:
```
$ cd my-repo
```
Git has now created a local copy of the GitLab repository and configured the GitLab repository as the remote named origin.

Verify the remote repository

$ git remote -v

You should see SSH addresses similar to:

origin  git@gitlab.com:jgalt/my-repo.git (fetch)
origin  git@gitlab.com:jgalt/my-repo.git (push)

Part 3 — Everyday Git Workflow

A common Git workflow is:

pull → edit → status → add → commit → push

Get the latest changes before you start working
```
$ cd my-repo
$ git pull
```
This downloads changes from GitLab and integrates them into your current local branch.

Check the status of your repository

$ git status

If there are no local changes, you may see output similar to:

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

Add changed files to the staging area
After creating or modifying files, check the status:
```
$ git status
```
Add individual files:
```
$ git add Foo.py
$ git add Bar.py
```
Or stage all changes in the current repository:
```
$ git add .
```
Commit your changes
```
$ git commit -m "Describe the changes you made"
```
Commit messages should briefly explain what changed.
Push your commit to GitLab
```
$ git push
```
You can also explicitly specify the remote and branch:
```
$ git push origin main
```
View the commit history
```
$ git log
```
For a shorter view:
```
$ git log --oneline
```
To visualize branches and merges:
```
$ git log --oneline --graph --all
```

Part 4 — Creating a Repository Locally First

Usually, it is simplest to create a repository on GitLab and clone it. However, you can also create a repository locally first and then connect it to GitLab.

Create an empty GitLab project
Create a project named another-repo on GitLab. For this example, do not initialize it with a README.

Create the local repository

The following commands work in macOS Terminal and Windows Git Bash:

$ mkdir another-repo
$ cd another-repo
$ git init -b main
$ touch README.md
$ git add README.md
$ git commit -m "Initial commit"

Connect the local repository to GitLab using SSH
Copy the project's Clone with SSH URL from GitLab. Then run:
```
$ git remote add origin git@gitlab.com:jgalt/another-repo.git
```
Verify the remote:
```
$ git remote -v
```
Push the initial commit
```
$ git push -u origin main
```
The -u option establishes origin/main as the upstream branch. Afterward, you can normally use:
```
$ git push
$ git pull
```

Part 5 — Working with Branches

Create and switch to a development branch
First make sure you are inside your repository:
```
$ cd another-repo
```
Create and switch to a branch named dev:
```
$ git switch -c dev
```
On older Git versions, you may instead see:
```
$ git checkout -b dev
```
List local branches
```
$ git branch
```
Example:
```
* dev
  main
```
The * identifies your current branch.

Make and commit changes on the development branch

$ touch newfile
$ git add newfile
$ git commit -m "Add newfile"

Push the development branch to GitLab
The first time you push the branch:
```
$ git push -u origin dev
```
GitLab will create the remote dev branch if it does not already exist.
Merge the development branch into main
Switch back to main:
```
$ git switch main
```
Get the latest remote changes:
```
$ git pull
```
Merge dev into main:
```
$ git merge dev
```
If Git reports a merge conflict, manually resolve the conflicting files, stage the resolved files with git add, and then complete the merge commit.
Push the updated main branch
```
$ git push
```

Part 6 — Forking a Repository

A fork creates your own GitLab copy of another GitLab project. Some course assignments may ask you to fork a repository before working on it.

Fork the project on GitLab
1. Open the GitLab project that you need to fork.
2. Select Fork.
3. Select your own GitLab namespace when asked where the fork should be created.
4. Create the fork.

Clone your fork using SSH

Open your fork, select Code → Clone with SSH, and copy the SSH URL.

For example:

git@gitlab.com:<YourGitLabID>/cs330e-collatz.git

Then clone it:

$ git clone git@gitlab.com:<YourGitLabID>/cs330e-collatz.git
$ cd cs330e-collatz

Verify that you cloned your own fork
```
$ git remote -v
```
The origin URL should contain your GitLab username or namespace.

Part 7 — Undoing Common Git Actions

Unstage a file before committing
```
$ git restore --staged <filename>
```
This removes the file from the staging area but keeps your changes in the working directory.
Discard changes to a file
```
$ git restore <filename>
```
Be careful.
This discards uncommitted changes to the file.
Undo the most recent local commit but keep the changes
```
$ git reset --soft HEAD~1
```
Use this primarily for a commit that has not been pushed. The changes remain staged.
Undo a commit that has already been shared
```
$ git revert <commit-hash>
```
git revert creates a new commit that reverses an earlier commit without rewriting shared Git history.

Quick Reference

Start working:

$ git pull
$ git status

Save and publish your work:

$ git add .
$ git commit -m "Describe your changes"
$ git push

View history:

$ git log --oneline --graph --all

Create a branch:

$ git switch -c dev

Switch branches:

$ git switch main
$ git switch dev

Check your GitLab remote:

$ git remote -v

Test GitLab SSH authentication:

$ ssh -T git@gitlab.com

SSH vs. HTTPS

This course documentation uses SSH for GitLab authentication. Once SSH is configured, you can normally clone, pull, and push without repeatedly entering GitLab credentials.

GitLab also supports HTTPS repository URLs, but unless an assignment specifically tells you otherwise, use the Clone with SSH URL shown on the GitLab project page.

SSH example:

git@gitlab.com:jgalt/my-repo.git

HTTPS URLs typically look like:

https://gitlab.com/jgalt/my-repo.git

If Something Goes Wrong

Before trying to fix a Git problem, run:

$ git status

Read the output carefully. Git will often tell you what state the repository is in and what action it expects next.

Also check that your repository is connected to the expected GitLab project:

$ git remote -v

If SSH authentication is the problem, test it separately:

$ ssh -T git@gitlab.com

If you are unsure how to recover from a Git problem, avoid commands that rewrite history or delete changes until you understand what they will do.

Additional Git Resources

For additional Git documentation, see the official Git documentation.

For GitLab SSH setup details, see the GitLab SSH documentation.