CS 235/250 Unit 04 Exercise: Source control and git

Table of Contents


1. Introduction

About
Source control is an important tool in software development. GitLab is a service that allows us to host git repositories. Our own computer will use the git software to interact with the GitLab server.
Goals
  • Set up git
  • Clone a repository
  • Make changes to a repository
  • Deal with merge conflicts
  • Create branches and merge requests
Setup
Make sure you have access to the learning repository:

2. Installing git

Starting off, you will need to install the git program to your computer. Go to https://git-scm.com/ and select Download for your OS. Make sure to read through the setup settings here to prevent headaches in the future. (In particular, not setting Vim as the default text editor… unless that's something you want.)

Most of the default settings are fine, but take note:

Select Components
Make sure that "Git Bash Here" is checked.
Choosing the default editor used by Git
Choose something like Notepad or if you have a preferred text editor, use that.

3. Configuring git

After git is installed, we will need to do a one-time configuration. Open up Git Bash (in Windows) or use git from your terminal (Linux/Mac).

You will need to configure your name:

git config --global user.email "you@example.com"

Replace "you@example.com" with your email (such as your student email).

And your email address:

git config --global user.name "Your Name"

Replace "Your Name" with your name, which is what will show up when you submit code file edits.

Finally, you will need to set the pull strategy to NOT rebase:

git config --global pull.rebase false

4. Cloning the repository

Your operating system: Navigate to the folder where you're storing your class projects. From here, right-click in the empty space and select Git Bash Here to open Git Bash.

Repository webpage: On the repository webpage (CS 235: https://gitlab.com/rsingh13-student-repos/2023-08_cs235/cs235-fall2023, CS 250: https://gitlab.com/rsingh13-student-repos/2023-08_cs250/2023-08_cs250) click on the blue Clone button and copy the URL listed under the Clone with HTTPS header. (You can use SSH if you know how to set it up, but we aren't going to cover that here.)

c3_u04_clone.png

Git Bash: Use the git clone URL command in Git Bash. This will clone the repository within the folder you opened Git Bash in. (Windows: To use PASTE, right-click in Git Bash… CTRL+V will not work here.)

$ git clone https://gitlab.com/rsingh13-student-repos/2023-08_cs235/cs235-fall2023.git
Cloning into 'cs235-fall2023'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
Receiving objects: 100% (3/3), done.

Now that the folder is on your computer, you will need to change directory into the folder. Use cd FOLDERNAME (in the example above, the folder name would be cs235-fall2023) to enter the repository folder in Git Bash.


5. Creating a branch

Command Description
git branch View available branches
git checkout -b BRANCHNAME Create a new branch with the given BRANCHNAME
git checkout BRANCHNAME Checkout an existing branch whose name matches the BRANCHNAME

When working on an assignment, you will need to create a new branch each time.

To view available branches, use the git branch command:

$ git branch
* main

To create a new branch, use the git checkout -b BRANCHNAME command, using your name and the assignment number in the branch name:

$ git checkout -b rsingh13_u04ex
Switched to a new branch 'rsingh13_u04ex'

Now if you type in git branch again you will see two branches with the asterisk marking which branch you're currently on:

$ git branch
  main
* rsingh13_u04ex

Each branch basically has its own code space. If you have work-in-progress code happening on separate branches, they will only be available on that specific branch. If you switch to another branch you'll only see code for that branch, but you can always keep switching between to get the code back. (When starting a new assignment, make sure to go back to the main branch and use git pull to grab latest code before then creating a new branch. I'll try to put a reminder in future assignments.)

If you want to switch between existing branches, use git checkout BRANCHNAME:

$ git checkout main
Switched to branch 'main'
Your branch is up to date with 'origin/main'.

$ git checkout rsingh13_u04ex 
Switched to branch 'rsingh13_u04ex'

(Note: The main branch might be named "master" so if your git branch shows "master" instead of "main", use that.)

Stay on your new branch, USERNAME_u04ex, for now.


6. Add, commit, and push

Command Description
ls List out the files and folders in the current directory
touch FILENAME Create a new file
echo "text" >> FILENAME Append text to a file
git status View files that have changed
git add FILENAME Add a specific file to the changeset
git add *.cpp Add all files that end with ".cpp" to the changeset
git add . Add all changed files to the changeset
git commit Create a snapshot of currently added changes
git commit -m "text" Create a snapshot of currently added changes, setting commit message at the same time
git push -u origin BRANCHNAME Push the changes in the branch to the server

Starting off, the learning repository only has the README and a folder:

$ ls
README.md  TextAdventure

Use the touch FILENAME command to create a new file. Name your file YOURNAME.txt . You can open the file from your OS and edit the text, or you can use the following command to put the text "Hello, I'm NAME!" in place:

$ echo "Hello, I'm Rachel!" >> rsingh13.txt 

Next, use the git status command to view the changed file:

$ git status
On branch rsingh13_u04ex
Untracked files:
  (use "git add <file>..." to include in what will be committed)
  rsingh13.txt

nothing added to commit but untracked files present (use "git add" to track)

We need to use the git add FILENAME command to mark the file for the changeset.

$ git add rsingh13.txt 

It won't show any confirmation message if there is no error.

Next, we use the git commit -m "COMMIT MESSAGE" command to make a snapshot of the file's changes at this point:

$ git commit -m "Created my text file"
[rsingh13_u04ex 9eb8e5c] Created my text file
 1 file changed, 1 insertion(+)
 create mode 100644 rsingh13.txt

Finally, use the git push -u origin BRANCHNAME command to push your changes to the GitLab server:

$ git push -u origin rsingh13_u04ex 
Enumerating objects: 4, done.
Counting objects: 100% (4/4), done.
Delta compression using up to 12 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 303 bytes | 303.00 KiB/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: 
remote: To create a merge request for rsingh13_u04ex, visit:
remote:   https://gitlab.com/rsingh13-student-repos/2023-08_cs235/cs235-fall2023/-/merge_requests/new?merge_request%5Bsource_branch%5D=rsingh13_u04ex
remote: 
To gitlab.com:rsingh13-student-repos/2023-08_cs235/cs235-fall2023.git
 * [new branch]      rsingh13_u04ex -> rsingh13_u04ex
Branch 'rsingh13_u04ex' set up to track remote branch 'rsingh13_u04ex' from 'origin'.

7. Pulling remote changes

Command Description
git pull Pull latest changes from the server

GitLab webpage: On the webpage your branch will now show up in the dropdown menu.

c3_u04_gitlab_branch.png

Select your branch and you'll be able to see the last commit and your file here:

c3_u04_gitlab_files.png

Open up your text file here and click the blue Edit button and select an editor. Add another line to the text file, then click the Commit changes button at the bottom of the page.

c3_u04_gitlab_commit.png

Git Bash: Use the git pull command here to pull all changes, which will grab the changes that you just made from the server.

$ git pull
remote: Enumerating objects: 5, done.
remote: Counting objects: 100% (5/5), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
Unpacking objects: 100% (3/3), 517 bytes | 517.00 KiB/s, done.
From gitlab.com:rsingh13-student-repos/2023-08_cs235/cs235-fall2023
   9eb8e5c..90394af  rsingh13_u04ex -> origin/rsingh13_u04ex
Updating 9eb8e5c..90394af
Fast-forward
 rsingh13.txt | 2 ++
 1 file changed, 2 insertions(+)

When you open the text file in Notepad or a text editor, you will now see the second line of text.


8. Dealing with merge conflicts

This time we're going to purposefully create a merge conflict. This happens when changes are made to the same file from different locations (such as on your computer and the web, or between different developers) and git can't figure out how to automatically merge the changes together. It can be intimidating to deal with, but it isn't too bad.

On your computer
  • Notepad/text editor: Edit your text file to add some text in the middle.
  • GitBash/terminal: Then use git add FILENAME , git commit -m "Edited file", but don't push yet.
On the web
  • GitLab webpage: Edit your text file to add a different line of text in the middle.

c3_u04_gitlab_twochanges.png

Git Bash: Now that you have two sets of changes, try to push your changes to the server. It will be rejected:

$ git push
To gitlab.com:rsingh13-student-repos/2023-08_cs235/cs235-fall2023.git
 ! [rejected]        rsingh13_u04ex -> rsingh13_u04ex (fetch first)
error: failed to push some refs to 'git@gitlab.com:rsingh13-student-repos/2023-08_cs235/cs235-fall2023.git'
hint: Updates were rejected because the remote contains work that you do
hint: not have locally. This is usually caused by another repository pushing
hint: to the same ref. You may want to first integrate the remote changes
hint: (e.g., 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

It gives you a hint - you need to use git pull to grab any latest changes from the server:

$ git push
To gitlab.com:rsingh13-student-repos/2023-08_cs235/cs235-fall2023.git
 ! [rejected]        rsingh13_u04ex -> rsingh13_u04ex (non-fast-forward)
error: failed to push some refs to 'git@gitlab.com:rsingh13-student-repos/2023-08_cs235/cs235-fall2023.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.
hint: See the 'Note about fast-forwards' in 'git push --help' for details.

Use git pull, which will work, but result in a merge conflict:

$ git pull
Auto-merging rsingh13.txt
CONFLICT (content): Merge conflict in rsingh13.txt
Automatic merge failed; fix conflicts and then commit the result.

Open the text file in your editor and you'll see some additions to the file:

Hello, I'm Rachel!
<<<<<<< HEAD
This is my third edit.
=======
Fourth update!!!
>>>>>>> a0c7bd54e2c5c19d1ebd41a84e7a6b8820573cf9
This is a second update!

There are two regions, and we need to manually decide how we want to merge the text. You could just remove the markers if you wanted both changes. Make the update and save the file:

Hello, I'm Rachel!
This is my third edit.
Fourth update!!!
This is a second update!

Then do your add, commit, and push to push the merged updates to the server.

Protip: You can combine multiple commands together with &&:

$ git add . && git commit -m "manual merge" && git push

GitLab: On the website, you can select the "Commits" link under the "Code" section to view all the changes you've made to the code:

c3_u04_gitlab_commitlist.png


9. Creating a merge request

Once changes are made, you'll create a merge request. This is how you can have your code reviewed, and the instructor will sign off on it and merge it to the main branch, where all the code will live together. This is similar to in software development, where everybody will work on their own features on their own branches, create a merge request, get their code reviewed, then a senior developer will merge the code into the main project.

GitLab: On the main repository page you will see a message saying that there are changes in your branch, with a button "Create merge request":

c3_u04_gitlab_mergenotif.png

You can mostly leave the defaults unless you want to add notes. Scroll down and click the blue "Create merge request" button.

There will be a merge request page generated:

c3_u04_gitlab_mergerequest2.png

The URL of this page is what you will usually turn in as your Exercise assignments


10. Making more code changes

Task: Create a new branch, go into the TextAdventure/data/maps.csv file, add a new map to the list, then add/commit/push and create a merge request for this feature.

On your computer
  • GitBash/terminal: Back in Git Bash, prepare for working on your next project with the following steps:
(no term)
Use git checkout main to go back to the main branch.
(no term)
Use git pull to get any latest changes from the main branch.
(no term)
Create a new branch with git checkout -b NAME_mapupdate

Locate the maps.csv file under TextAdventure/data/ on your computer. You can open this file in a plaintext editor or a spreadsheet editor. This file contains map locations in a text adventure game. Set one item's name and desc fields.

After making the updates, add/commit/push and create a new merge request:

  1. Use git add . to add changed files.
  2. Use git commit -m "Updated map file" to make a change snapshot.
  3. Use git push to push your changes to the server.
    • GitLab webpage: Create a new Merge Request.

Author: Rachel Wil Sha Singh

Created: 2023-09-12 Tue 15:34

Validate