Lab0: Gitting Started

Time Estimate2 Hours Grade Impact2.5% DueSep 9 @ 3pm Required for Pass

You finally get to learn how to use Git—congratulations!

Objective
Become familiar with Linux, Git, and the basic user interface required for this course’s labs.

Additional Materials & Formats
Check Box for the most up-to-date versions of this lecture’s materials.

A Word of Warning
Before starting any lab, always read the entire lab description. You will be working with expensive, fragile hardware. Look particularly closely at these boxes, which warn you of potential problems.

Before the Lab

Equipment

Please bring the following equipment to this lab:

Note taking mechanism (laptop, notebook, etc.)

Pre-Lab Work

This lab does not have pre-lab tasks. Future labs will require some work in advance.

ECE Lab Machines

Log into any lab machine with your A-Number and secure USU password. Every machine will offer a synchronized, comparable experience, so you can use whichever machine you like.

When you log in for the first time, you’ll see the following blank desktop:

The lab machines are configured to run a Linux operating system. Linux is a powerful, open-source platform widely used in engineering and development environments.

If you are unfamiliar with Linux, it is recommended to review basic concepts to understand navigation. Recent improvements to Linux make it extremely user-friendly, offering both graphical and command line options for most features. A helpful starting point is this the Linux Cheat Sheet. Understanding these concepts will make your experience with the operating system more efficient.

It is my hope and my belief that you will start to develop an appreciation for Linux in this course. Take caution, as this appreciation can quickly become a hobby, then a lifestyle, then an entire personality.

Saving your work

To ensure your work is not lost, it is crucial to save your progress frequently. The lab machines delete your data every midnight, so you are responsible to keep your data backed up. Viable backup options include a physical flash drive or hard disk, an online file manager (e.g., Box, OneDrive, Google Drive, Proton Drive, etc.), and/or a Git repository (recommended).

We are hosting our code on GitHub for this course to facilitate remote storage, collaboration, and other handy features. This practice will safeguard your files against accidental deletion or hardware issues.

Lost Data
You are responsible for backing up your own data. This means that lost data due to hard drive failure or other machine faults will not excuse late or missing submissions. Back up your work frequently.

On these machines, the nickname/shortcut for your home directory is a tilde ~, so you can always navigate to this directory with this command:

cd ~

Create a subdirectory from your home directory. On the command line, you can do this with mkdir <name>. In the file browser, you can click F10 to create a new directory. Call this directory ece2700. You can now navigate to your ece2700 directory from any directory on your machine with the following command:

cd ~/ece2700

You can autocomplete folders by clicking the Tab key when you’ve typed enough characters. If you want to list every file that starts with Lab, for example, type in cat Lab then click Tab. If nothing autofills, click Tab once again, and you’ll see a list of files and folders that start with Lab.

This course doesn’t include a thorough exploration of Linux, buy you’re encouraged to learn more independently about how to get the most out of this operating system.

Exercise: Navigating the Linux Filesystem

Practice navigating the Linux filesystem with the following steps:

Open the Terminal: Launch the terminal on your lab machine. You’ll see a display similar to this:

List Files and Directories: Use the ls command to list the contents of your current directory.
```
ls
```
Navigate to the Home Directory: Use the cd command to move to your home directory.
```
cd ~
```
Create a New Directory: Create a directory named linux_practice.
```
mkdir linux_practice
```
Navigate into the New Directory: Move into the linux_practice directory.
```
cd linux_practice
```
Create a File with Content: Create a new file named example.txt and write some text into it using the echo command.
```
echo "Hello, Linux!" > example.txt
```
Display the File’s Content: Use the cat command to display the content of example.txt on the terminal.
```
cat example.txt
```
Rename the File: Rename example.txt to greeting.txt using the mv command.
```
mv example.txt greeting.txt
```
Verify the File’s New Name: Use the ls command to confirm the file has been renamed.
```
ls
```
Move the File to the Parent Directory: Move greeting.txt to the parent directory.
```
mv greeting.txt ..
```
Navigate Back to the Parent Directory: Use cd .. to move to the parent directory.
```
cd ..
```
Delete the File: Remove greeting.txt using the rm command.
```
rm greeting.txt
```
Remove the Directory: Delete the linux_practice directory.
```
rm -r linux_practice
```

Remember, organizing your directories and files properly will make it easier to locate your work and avoid confusion as you progress through the labs.

Git

You are required to use Git to manage your coursework. Git is a powerful version control system that allows you to track changes in your code, collaborate with others, and maintain a history of your work. Its distributed nature ensures that every contributor has a complete copy of the repository, providing redundancy and flexibility. Git enables branching and merging, making it easy to experiment without affecting the main codebase. Additionally, platforms like GitHub facilitate remote collaboration and project management.

Using GitHub & Github Classroom

For this course, we will use GitHub Classroom to streamline things. To start, follow these steps:

Create an Account: If you do not have a GitHub account, sign up for one. Now is also a good time to set up access to Github Education features, if you would like. Choose a nice username and save your password; you’ll probably have this account for many years.
Accept the Invitation: There is an invitation link to join the classroom and another link for this lab in Canvas. Click them. This will create a private repository for you under the course’s GitHub Classroom organization. After clicking the link, you may see an error page indicating you don’t yet have access, like I always do. Here’s what to do:
- Wait about 1 minute for everything to finish on Github’s server.
- Check your email for a notification about joining a new repository. If there’s nothing there, go to the Github Homepage and view your notifications in the top right corner:
- In either the email or the notification, click “Accept Invitation”. Now you have access.
Set up Authentication: Follow GitHub’s instructions for either method.
- Option 1: Connect with an SSH Key – Best practice; however, because the lab machines will delete your SSH key every day at midnight, it is more practical to use Option 2 for this course.
- Option 2: Use a Personal Access Token – This option is going to be easiest for this course. Create a Personal Access Token and make sure it has permissions for read/write on whatever repositories you’ll need for this course (i.e., the ece2700 organization). Follow these steps:
  1. Click your profile photo in the top-right corner, then click Settings.
  2. Click Developer Settings, which is the last item in the left sidebar menu.
  3. Click Personal Access Tokens, then Fine-grained Tokens.
  4. Click Generate new token.
  5. Enter ECE 2700 for the Token name. A clear name helps you maintain your account security.
  6. Ensure your username is selected as the Resource owner.
  7. Set the Expiration to a date after the conclusion of this course, perhaps 31 December 2026.
  8. Set Repository access to All repositories to enable this token to be used on repositories you join in the future.
  9. Click Add permissions and select Contents.
  10. In the list that appears, change Access to Read and write.
  11. Click Generate token, then confirm in the popup box.
  12. Securely save the token that pops up. Secure storage options include: a file on Box, a password manager, an encrypted file on a flash drive, etc. Do not save the token to a lab computer.
Once you have configured your Personal Access Token, you can use it in place of a password when you interact with GitHub via the command line. On the web interface at github.com, you should still use your original GitHub password/passkey.
Clone Your Repository: Next, you will clone your new repository to work on your own machine. Use the <> Code button on your repository page to copy the clone URL. Then, run the following command in your terminal:
```
git clone <clone-url> <new-name>
```
Replace <clone-url> with the URL you copied. The repository has a very long name, so you can optionally replace <new-name> with a shorter version, something like Lab0.
Celebrate: Congratulations! You’ve set up and cloned a repository and you’re ready to go! By using the repository from GitHub Classroom, you can easily manage your coursework and ensure your instructor has access to your submissions. Your instructor (@mossbiscuits on GitHub) will already have access to your repository through GitHub Classroom. No additional steps are needed. We’ll cover steps to collaborate effectively later in this lab.

Your First Commit

On the command line, navigate to the folder you just cloned. You can do that with this command:

cd <new-name>

Remember to replace <new-name> with the name of the folder you just cloned. If your current directory is already ece2700, you can simply use cd <new-name>. Or you can try using Tab to complete: type cd then space, then click the Tab key. It should autofill your new directory name if it is the only subfolder.

Next, let’s create a new branch to do our work. We don’t want to do any experimenting in the main branch, so let’s create a new branch for this project:

git branch test

Now we have a branch called test to work in, and we need to do a checkout to start working in the test branch instead of the main branch:

git checkout test

Next, let’s verify what branch we’re currently working in:

git branch

This will print the current branch. You should see an asterisk (*) next to test, indicating you are on the test branch.

Now, let’s make the first commit on this branch. First, let’s add some text to a new file called branch_test.txt:

echo "This is a test branch." > branch_test.txt

Add the file to Git’s staging area so that Git starts tracking changes to it. This step prepares the file for the next commit. This tells Git to include branch_test.txt in the next commit.

git add branch_test.txt

You can use the Linux file shortcuts to add multiple files. For example, to add every file in the project directory to the staging area, use git add project. If you would like to add all of your updates to the staging area instead of specific files, you can use git add -A.

A commit in Git is like taking a snapshot of your project at a specific point in time. It records the changes you’ve made to your files and allows you to save your progress. Think of it as a checkpoint in a video game—you can always return to this point if something goes wrong later. Each commit should have a descriptive message that explains what changes were made and why. This helps you and your collaborators understand the history of the project.

To commit the changes, use the following command:

git commit -m "Add test file"

The -m flag allows you to include a message directly in the command. Commit messages ideally start with an active verb. Replace "Add branch_test.txt to test branch" with a message that clearly describes what you did. For example, if you fixed a bug, your message might be "Fix bug in login functionality". Aim for clarity and brevity in your commit messages.

If you do not specify a message and only run git commit, a text file will open asking you to supply one. When you save and exit the text editor, the first line in the text file will be used as the commit message.

Next, push the changes to the remote repository. When you push changes, you are uploading your commits from your local repository to a remote repository, such as one hosted on GitHub. This ensures that your work is saved on a remote server, making it accessible to collaborators and safeguarding it against data loss on your local machine.

A push typically looks like this:

git push

If you are pushing to a new branch for the first time, you may need to specify the upstream branch:

git push --set-upstream origin <branch-name>

Here, origin refers to the default name of the remote repository, and <branch-name> is the branch you are pushing. For example,

git push --set-upstream origin test

The --set-upstream flag ensures that your local test branch is linked to the remote test branch. From now on, you can simply use git push to push changes.

Merging Branches

Merging branches allows developers to integrate changes from different branches into a single codebase, ensuring that features, bug fixes, or updates are combined seamlessly. For example, a team might work on separate branches for new features, and once those features are complete and tested, they are merged into the main branch to prepare for release. This process helps maintain a clean and organized workflow, as developers can work independently without interfering with the stable version of the project.

Once you’re satisfied with the changes in your test branch, you can merge them into the main branch. First, switch back to the main branch:

git checkout main

Merge the test branch into main:

git merge test

If there are no conflicts, the merge will complete successfully. Push the updated main branch to the remote repository:

git push

Pull Requests

While a simple merge allows you to directly integrate changes from one branch into another, pull requests (PRs) provide a more structured and collaborative approach to merging. A PR is a feature offered by platforms like GitHub that facilitates code review and discussion before merging changes. Under the hood, a PR performs git merge once it is approved, but it offers great front-end features to prevent chaos.

Why use a PR instead of `git merge` directly?

Collaboration: Pull requests enable team members to review, comment, and suggest changes to the code before it is merged. A simple merge does not inherently include this review process.
Transparency: PRs create a clear record of what changes are being proposed, why they are necessary, and any discussions or decisions made during the review process.
Approval Workflow: Pull requests often require approval from one or more reviewers before the changes can be merged, ensuring code quality and consistency.
Integration Checks: Many repositories are configured to run automated tests or checks on the code in a pull request, ensuring that the proposed changes do not introduce errors.

Feedback Pull Request

When you accept the GitHub Classroom invitation for this lab, a special feedback pull request (PR) is automatically created. This PR serves as a communication channel between you and your instructor. It allows your instructor to review your work, provide comments, and suggest improvements directly within your repository.

The feedback PR is not meant to be merged into your main branch. Instead, it remains open to facilitate ongoing feedback. You can address comments by making changes in your repository and pushing updates. These updates will automatically appear in the feedback PR.

To view the feedback PR:

Navigate to your repository on GitHub.
Click on the “Pull requests” tab.
Select the feedback PR.

If you’d like to request feedback, you have a few options. I would recommend trying this during this lab, since I will actively monitor repositories and confirm that your workflow is effective. I can help you if you get stuck.

Mention @mossbiscuits in a new comment and ask a specific question. In comments, you can also link to specific lines in your code, issues, or commits. This is the most effective way to get help on a lab.
In the sidebar, request a review from @mossbiscuits. I will receive an email about this request and leave comments throughout your codebase. This is great if you want me to take a look at your entire codebase, or you can ask a specific question in the PR comments.
As always, you can email or message me directly. It is helpful to me if you provide a link to whatever you need to reference on Github. This option is extra work for everyone, but it is an option.

Navigating GitHub’s Pull Request Pages

GitHub’s Pull Request (PR) pages provide a comprehensive interface for reviewing, discussing, and managing changes. Here’s a quick guide to navigating these pages:

Conversation Tab: This is where discussions about the PR take place. It shows a summary of the changes, the description provided by the author, and any comments or reviews. You can reply to comments, resolve conversations, and see the overall activity. You can also merge the PR directly from this page. In the sidebar, you can request reviews, assign someone to look at the PR, and use other collaboration features.
Commits Tab: This tab lists all the commits included in the PR. You can click on individual commits to view their details.
Checks Tab: If the repository has automated tests or workflows, their results will appear here. This helps ensure that the changes meet the project’s quality standards.
Files Changed Tab: This tab displays a side-by-side or unified view of the code changes in the PR. You can leave comments on specific lines of code by clicking the + icon next to the line numbers.

Creating a Pull Request:

These steps will let you create your first PR.

Go back to working in your test branch:
```
git checkout test
```
Open the branch_test.txt file and add a new line of text. You can use the echo command to append text to the file:
```
echo "This is an additional line in the test branch." >> branch_test.txt
```
Add the modified file to the staging area:
```
git add branch_test.txt
```
Commit the changes with a descriptive message:
```
git commit -m "Add line to test file"
```
Push the updated test branch to the remote repository:
```
git push origin test
```
Navigate to your repository on GitHub and click the “Compare & pull request” button, or create a PR directly from the “Pull Requests” page.
Add a title and description for your pull request, explaining the changes and their purpose.
Assign reviewers, if necessary, and submit the pull request.

Merging a Pull Request:

Once the pull request is approved (whatever that means for you), you can merge it into the target branch. This can be done directly on GitHub by clicking the “Merge pull request” button.

Pull requests are especially useful in collaborative projects, as they encourage communication and ensure that all changes are thoroughly reviewed before being integrated into the main codebase.

The `main` Branch

In this course, the main branch in your GitHub Classroom repository represents the “submitted version” of your work. In real life, the main branch is usually the code that makes up the released work. The main branch is the branch that will be graded. Ensure that all final changes are merged into the main branch before the submission deadline.

To avoid accidental changes to the main branch, it is recommended to create and work on separate branches for each task or feature. Once your work is complete and tested, merge it into the main branch.

Before merging, double-check that:

All required files are present and up-to-date.
Your code is functional and free of errors.
Commit messages are clear and descriptive.

After merging, push the updated main branch to the remote repository:

git push origin main

This ensures that your instructor has access to the latest version of your work.

Deleting the Test Branch

After merging, you can delete the test branch if it’s no longer needed:

git branch -d test

If the branch has been pushed to the remote repository, delete it there as well:

git push origin --delete test

Congratulations! You’ve successfully created, worked on, and merged a Git branch.

Exercise: Adding Tags to Your Classroom Project

Follow these steps to practice creating and managing tags in your GitHub Classroom project:

Navigate to Your Repository: Open your terminal and navigate to your cloned repository:
```
cd <repository>
```
Create a Tag for Your First Commit: Tag the commit where you added the branch_test.txt file:
```
git tag -a first-commit -m "Added branch_test.txt"
```
Push Tags to the Remote Repository: Push the tags to GitHub:
```
git push --tags
```
Verify Tags on GitHub: Navigate to your repository on GitHub and check the “Tags” section to ensure your tags are visible.
Delete a Tag Locally: Practice deleting a tag locally:
```
git tag -d first-commit
```
Delete a Tag Remotely: Delete the same tag from the remote repository:
```
git push origin --delete first-commit
```

Recreate and Push the Deleted Tag: Recreate the first-commit tag and push it again:

git tag -a first-commit -m "Added branch_test.txt"
git push origin first-commit

Tags are a valuable tool for marking milestones and organizing your project’s history. We’ll use them extensibly to mark the milestones in our labs. In future labs, you’ll see Deliverable Checkpoints with tagging instructions. Remember to follow these instructions, which look like the following:

Deliverable Checkpoint
Submit your work at this stage by tagging your current commit <tag goes here> and pushing tags.

More Practice

If you want to practice and learn more about some of Git’s advanced features, I strongly recommend these tutorials:

Here are some additional resources that might help you:

Git Documentation: The official Git documentation is an excellent resource for understanding Git commands and workflows.
Linux Command Cheat Sheet: A handy Linux command cheat sheet for quick reference.
Markdown Guide: If you’re unfamiliar with Markdown, check out this Markdown Guide to learn how to format README and other text on Github effectively.
GitHub Student Pack: If you haven’t already, sign up for the GitHub Student Developer Pack to access free tools and resources.

Feel free to explore these resources to enhance your understanding and make your lab experience smoother.

Deliverables

To submit your deliverables for this lab and future labs, follow these steps. Full points are awarded to students who complete these steps.

Work on a New Branch: Create and checkout a new branch, named whatever you like. Create a file called hello_git.txt and fill it with some text.
Ensure All Work is Committed: Verify that all your changes are committed to your current branch. Use the following commands to check the status and commit any remaining changes:
```
git status
git add -A
git commit -m "Finalize lab deliverables"
```
Switch to the main Branch: Move to the main branch to prepare for merging:
```
git checkout main
```
Merge Your Work into main: Merge the branch you have been working in (e.g., feature-branch) into main. Replace feature-branch with the name of your branch:
```
git merge feature-branch
```
Resolve Any Merge Conflicts: If there are merge conflicts, resolve them by editing the conflicting files. After resolving, add the resolved files to the staging area:
```
git add <file-name>
```
Once all conflicts are resolved, complete the merge:
```
git commit
```
Push Changes to GitHub: Push your updated main branch to the remote repository:
```
git push origin main
```
Tag Your Submission: Create a tag named done to mark your submission:
```
git tag -a done -m "Lab0 submission"
git push origin done
```
Verify on GitHub: Navigate to your repository on GitHub and confirm that:
- All your files are present in the main branch.
- The done tag is visible under the “Tags” section.
Check the Feedback Pull Request: Indicate to your instructor that you’re ready to submit your work by leaving a comment on the Feedback PR and requesting a review from @mossbiscuits. If you took photos, screenshots, or videos, remember to upload them to Box or Onedrive and link to them in the Feedback PR. Alternatively, you can submit these items directly on Canvas.

Your submission is now complete. Congratulations on finishing Lab0!

Grading

This lab is worth 100 points, awarded as follows:

(50) Lab session attendance
(30) Respository setup
(20) Correct use of Git and GitHub

Lab0: Gitting Started

Before the Lab

Equipment

Pre-Lab Work

ECE Lab Machines

Saving your work

Exercise: Navigating the Linux Filesystem

Git

Using GitHub & Github Classroom

Your First Commit

Merging Branches

Pull Requests

Why use a PR instead of git merge directly?

Feedback Pull Request

Navigating GitHub’s Pull Request Pages

Creating a Pull Request:

Merging a Pull Request:

The main Branch

Deleting the Test Branch

Tags

Exercise: Adding Tags to Your Classroom Project

More Practice

Deliverables

Grading

Why use a PR instead of `git merge` directly?

The `main` Branch