Set Up Your Computer
You may either work with our codebase on your personal computer or on our
dedicated lab machines. If you'd like to use the lab machines, skip to the
next section.
Ubuntu: If you have a computer that natively runs Ubuntu (versions 20.04 or later),
it should be easy for you to compile our code on your computer. There's nothing
extra for you to do now. Instructions for compiling the code are in a later
section.
Windows: If you have a computer that runs Windows, your best option is
to use Windows Subsystem for Linux. We recommend following
these instructions
to install the latest LTS release of Ubuntu (version 22.04 as of writing this).
Mac: If you have a mac that's running a recent version of macOS, you
should be able to compile natively on your machine as well. This includes
macs with an Intel CPU or Apple silicon. There is nothing extra for you to
do now.
Access Lab Computers (Optional)
If you prefer, you may access and manipulate the code from the lab computers.
Here's a list of available computers running Ubuntu:
baretta
blackwidowers
columbo
joefriday
perrymason
zenigata
scarpetta
To access one of the computers, make sure that you are on the IllinoisNet network. You will not be able to access our machines using the eduroam network. For guidance on how to access IllinoisNet through VPN, please click the link here.
You can connect to a lab computer from your terminal, with ssh netid@computername.cs.illinois.edu. When prompted for a password, please enter your uiuc password.
You could also connect to the lab machines using the VS Code editor (recommended). This is an easy way to access the computers while still being able to use a modern editor with a built in terminal. To do this, download VS Code and follow the 'Installation' and 'Connect to a remote host' instructions here: https://code.visualstudio.com/docs/remote/ssh.
Alternatively, you can use FastX for remote access. This is necessary to use Vizmo (covered later).
Follow instructions for installing a desktop client
Click to add a new host
Choose ssh
Fill in pop-up window your ssh information
Initialize connection
Enter your username password
Start a new session
You should now see the machine lab's display.
Git Tutorial Introduction
The rest of this lesson is a guide/tutorial intended to give you some familiarity with version control and how to resolve issues like merge conflicts.
What is Git?
Git is a distributed version control system that allows multiple people to work on a project simultaneously without overwriting each other's changes. Git tracks changes in a set of files, or a "repository," over time so that you can recall specific versions later. It is primarily used for source code management in software development but can be used to track changes in any set of files.
What is GitHub?
We host all of our lab's code on GitHub. GitHub is a web-based hosting service for Git repositories. It provides a graphical interface for managing repositories and includes additional features like bug tracking, task management, and continuous integration. While Git is a command-line tool that handles the "back end" (storing versions of files), GitHub provides a "front end" that makes it easier to manage projects and collaborate with others.
Parasol GitHub Organization
The Parasol Lab has its own GitHub organization, which is used to group all of our repositories together. Once you've been added to this organization, you should be able to see all of our repositories through the GitHub website. We'll walk through a simple tutorial to give you familiarity with the basic Git functions you'll need to know to work with our code.
Set up your ssh keys
An SSH key allows your computer to talk to the repository (also called repo) from the command line without
having to type your username and password every time.
Having an SSH key configured will let you push/pull from the repo through
the 'git@...' URLs without typing your username and password (SSH keys do
not work with https URLs). If you're using a lab machine, connect to it now,
otherwise follow these instructions on your personal computer.
Open a terminal and follow
these instructions provided by GitHub
to generate an SSH key and add it to your account.
Then, because our organization is linked to the UIUC Enterprise GitHub license, follow
these instructions
to authorize your SSH key to be used with the Parasol Lab organization.
Git Configuration
In the terminal, run the following two commands to configure Git with your information:
git config --global user.name "your name": The user name can
be any appropriate string - it is the name that your commit messages will
show. Please use your real name so that other students
can identify the author of a commit.
git config --global user.email "myemail": If you are a visiting
student with no Illinois email, you will want to use your
school email here and add it to your GitHub account as well. This will ensure that git matches
your old commits to your new account. If you are joining the group at
UIUC, use your UI email address here.
Cloning a Repository
“Cloning” is the process of pulling an existing repository onto your local
machine. We've made an example repository for use with this tutorial called
git-tutorial. Visit this webpage to see it:
https://github.com/parasollab/git-tutorial.
On that page, click Clone and then copy the SSH url.
In the terminal, use the cd <directory> command to navigate to
the directory where you'd like to store this repo (maybe ~/Desktop). Then,
clone the repo by running git clone <paste_url_here>.
Change directory into this new repo (cd git-tutorial) and open it up
in your favorite editor (VS Code, vim, etc.). You should see that this repo
is made up (almost) entirely of ASCII art (how fun!). Your job for the rest
of the tutorial will be to make a new branch, add a work of art, and add
your name to the list of artists.
Making a New Branch
Branches in Git are used to create isolated environments within a repository
to implement and test new features without affecting the main code base.
This is especially helpful when you're working in a team and you want to
avoid any potential conflicts with others' code.
Follow these instructions to make your own branch:
In the terminal, run git branch <branch-name>. Call your
branch something like “<your_name>-art”.
Switch to your new branch by running git checkout <branch-name>.
This is how you can switch to any branch in the repo.
Working in a Repository
Now, you'll make your artwork - remember to be appropriate, your labmates
will see this. Make a new file in the artwork directory, call it
whatever you'd like. If you're working directly in the terminal (rather than
e.g. VS Code) you can do this by running touch <your_file_name>
and vim <your_file_name> to open it. Then, draw your work of
art. Alternatively, there are many ASCII art generators you can use as well,
even ChatGPT will work. Make sure you save your file in the artwork folder
when you finish (if using Vim, type escape then ":wq").
Committing Changes
A commit in Git is like a snapshot or a checkpoint in your project's history.
It captures the state of your project (specifically, of the tracked files in
your project) at a particular point in time.
When you make a commit, Git records the changes you've made since the last
commit, the time the commit was made, and the author of the changes. Each
commit also has a unique ID (often referred to as a commit hash), which you
can use to refer to that specific set of changes.
Typically, you would make a commit when you reach a logical stopping point
in your work, for instance, after you've implemented a new feature, fixed a
bug, or made a significant edit. It's good practice to make frequent,
well-documented commits. This way, if you need to revert some changes or
track when a particular change was made, it will be much easier.
Use the git status command to see which files you've changed. Next,
use git add <file_name> to add each of the files you've changed
to the commit (e.g. git add artwork/dog.txt). Try to avoid using 'git add .'.
When you make a commit, you also include a commit message, which is a brief
description of the changes included in the commit. This message is important
for documenting your changes and helps others (and your future self)
understand what changes were made and why. Run git commit -m “Added art for [your subject]”.
Fixing Merge Conflicts
A merge conflict occurs in Git when two or more contributors make changes to
the same line of a file or when one person edits a file and another person
deletes the same file. The conflict arises when you try to merge these
changes together, and Git doesn't know which change should take precedence.
When a merge conflict happens, Git will pause the merge process, and it's up
to you to resolve the conflict manually. We're going to artificially
manufacture a merge conflict by creating two conflicting commits to give you
experience with resolving them.
Make a new branch based on your original branch and switch to the new branch.
This command will allow you to do all of that simultaneously:
git checkout -b <your_new_branch_name> <your_original_branch>.
Call your new branch something like <your_name>-temp.
Now, open up artists.txt and add your name to the bottom of the list,
but misspell it somehow. We'll correct it soon. Then, add this file to the
commit by running git add artists.txt and make a commit with a message:
git commit -m “misspelling my name”.
Go back to your original branch: git checkout <original_branch>.
Open up artists.txt and add your name to the bottom of the list,
spelled correctly. Make a new commit using git add artists.txt and
git commit -m “spelling my name correctly”.
We now have two conflicting merges, let's try to put them together and see
how Git responds. Run git merge <your_new_branch>. Note that in
general, we will not use the 'merge' command, but instead create pull
requests (covered later in the tutorial). You should see something like
CONFLICT (content): Merge conflict in artists.txt. Open up
artists.txt and you should see tags like this surrounding your name:
<<<<<<< HEAD
<your_correct_name>
=======
<your_misspelled_name>
>>>>>>> new_branch
These divider tags show you which branch has which version of the file. HEAD
refers to your current branch. Edit the file to remove the extra tags and
the misspelled name (i.e. the only thing that should be left of the above
snippet is <your_correct_name>). You've now corrected the file. We'll
make a new commit to tell Git that you've resolved the issue, run
git add artists.txt and git commit -m “resolved merge conflict”.
Pushing Changes to the Remote Server
Pushing your commit is the process of taking your local changes and putting
them onto GitHub's servers. Push your current changes by running git push.
The first time you try to push, Git will likely tell you to set an upstream
branch. This is the branch on the remote server that your local branch
corresponds to. We can do that by running:
git push --set-upstream origin <your_original_branch>. Now, the
next time you push, you can use git push alone.
Making a Pull Request
Now your changes are pushed to your personal (original) branch. Next, you'll
pull them into the 'main' branch. A merge request is a way to merge changes
from one branch to another, typically from a new feature branch into the
main branch. It's also a process for requesting that your changes be
reviewed by others before they get merged.
Here's how you create a pull request in GitHub:
Make sure your branch is up to date with the main branch by pulling
any new changes to the main branch into your personal branch:
git pull origin main. If there were any changes, commit and push
them. For reference, the git pull command will take any new
changes on the server and bring them into your local copy. Without any
additional arguments specified, it will default to pulling changes from
your current branch. You can specify a different branch to pull remote
changes from using git pull origin <other-branch-name>.
Then, go to the GitHub website and view the
git-tutorial repo.
Here, click Pull Requests and make a new pull request.
Set the source and target branches. In the "compare" field (the source),
select your personal branch. In the "base" field (the target), select the
branch which you want to merge your changes into, this is the main branch.
Create the pull request.
Give your pull request a meaningful title and a detailed description
so potential reviewers understand the purpose of your changes.
Typically, you'd assign a reviewer to perform a code review and
approve your changes. Here, we'll skip that since this is just meant
for educational purposes.
Click Create pull request.
Typically, your reviewer would take over here. But, for now, you can merge
your changes yourself. Click Merge pull request. If you don't see that option,
something has gone wrong and you should check with your grad mentor.
Finishing Up
Now that your art has been added to the main branch, check out the main
branch and pull remote changes so that your local copy is up to date. Switch
to the main branch using git checkout main and pull changes using
git pull. You should now be able to see your artwork and your name in
the list of artists.
