exercises.md

Exercises

Exercise 1: Setup

1. Make an account on GitHub.

2. Download git using the official Git installation guide.

3. Open your terminal.

4. Set up your local machine with the name and email that you want to appear on every commit.

   git config --global user.name "Your Name"
   git config --global user.email "your_email@example.com"

5. Create a Secure Shell (SSH) key. This helps GitHub authenticate your commits.

   ssh-keygen -t ed25519 -c "your_email@example.com"

   When prompted to "Enter a file in which to save the key," you can press Enter to accept the default. (You could pick a different location, but I find that I can only remember the default location).

6. Print out the contents of the public key and copy it.

   cat /path/to/public/key

   The path to the public key, if you saved it in the default, is probably something like /Users/username/.ssh/id_ed25519.pub or /home/username/.ssh/id_ed25519.pub.

7. Add the SSH key to your GitHub account using the official GitHub instructions.

Setup is complete! You are ready to start contributing.

Exercise 2: Getting ready to contribute to someone else's repo

Forking a repository is useful when you want to make edits to a repository that you do not have write permissions for. We will be doing exercises out of my git_practice repository today, and you do not have write permissions to this repository. To get around this, you will fork my repo, which means making a copy of it that belongs to you. You can make changes to your fork of the repository (known as an origin remote).

(A remote is just a repo that lives on GitHub).

1. Open the repository in your browser window. Fork the repository by clicking on the "Fork" button.

   

2. In your terminal, navigate to the directory where you would like to keep your workshop materials.

   cd /path/to/directory

3. Clone your exercise repository.

   git clone (git@github.com:YourUsername/git_practice.git)

   To easily find this URL, click on the green "<> Code" button, and select SSH.

   

4. Add an upstream remote. An upstream remote is the official repo on GitHub that you would like to make changes to. In this case, the upstream is my repository.

   git remote add upstream https://github.com/AlabamaWaterInstitute/git_practice.git

   To easily find this URL, click on the green "<> Code" button, and select SSH.

   

   Notice that for your origin remote, we clone with the SSH URL. This is because GitHub requires you to use SSH to authenticate whenever you push commits to the remote repo. Because you can't directly contribute to the upstream remote, we can just clone with the HTTPS URL.

5. Let's see our remotes.

   git remote -v

   Here, the -v flag means "verbose," because we want to see the details of our remotes. Our remotes are named origin and upstream, which are just common naming conventions. They could be named whatever you want, but we will stick with origin and upstream for this workshop.

Exercise 3: Your first contribution

In exercise_files/roster.txt, we will keep a list of the names of everyone who attended this workshop. Let's add your name to the list.

It's good practice to do your development work in a local development branch so that it doesn't change the main branch.

1. Create a new development branch from the most recent copy of the upstream remote.

   git fetch upstream
   git checkout upstream/main
   git checkout -b roster

   git fetch upstream updates your local copy of upstream. git checkout upstream/main creates a "detached HEAD," which is a fancy way of saying that you are just checking out a specific commit, and not a branch. We are checking out a commit from upstream because we want the most recent version of the repo, since there will be lots of contributors to this repo. "Checking out" is the git way of making a branch visible in your working directory. git checkout -b roster creates a new local branch called roster and also checks out the branch.

2. Open up exercise_files/roster.txt and add your name to the list. Make sure to save!

3. Did Git notice your local changes?

   git status

   This will show you the "changes not staged for commit.

4. Stage your change.

   git add .

5. Commit your change. Give the commit message a short description of the change you made.

   git commit -m "my message here"

   Good commit messages are short. Longer descriptions of the changes you made can be done in a pull request.

6. Push your local change up to your origin remote.

   git push origin roster

   This command creates a branch called roster in your origin remote.

7. Open your first pull request (often referred to as a PR). Navigate to the upstream remote's GitHub page. There will probably be a highlighted button saying that there were changes to a fork and prompting you to open a pull request. In the PR, you can explain the changes you made and the reasoning behind it. Once a maintainer of the repository accepts your PR, your changes will be merged with the upstream remote!

Note: We usually don't have ~10 people working on the same repository at the same time. This puts us at risk of a merge conflict, where the changes you are trying to contribute conflict with what is in the upstream main branch. If this happens, the GitHub will not let your PR be merged. There should be a button on the GitHub PR page that will walk you through how to resolve a merge conflict.

Exercise 4: The add/commit cycle, ad nauseam

To build your muscle memory, we will repeatedly make a change, stage the change with git add, and commit the change to your local branch with git commit. This may seem tedious, but it makes up a whole lot of the Git workflow. We will be editing exercise_files/favorite_things.md. For help with Markdown syntax, take a look at this cheat sheet.

1. Update your local copies of upstream and origin, as well as your origin remote.

   git checkout main # check out your local main branch
   git pull --rebase upstream main # fetch the upstream remote, merge any changes in upstream into your local main branch
   git push # push any changes in your local main branch up to your origin remote

   This is good practice before you make any changes so that you know you're working off the most recent codebase.

2. Create a new development branch.

   git fetch upstream
   git checkout upstream/main
   git checkout -b favorite-things

3. For each favorite thing, make a change to the markdown file, stage it with git add, and commit the change with git commit -m "your message". By the end of this, you should have 10 commits.

4. Push your local changes to your origin remote.

   git push origin favorite-things

5. Open a pull request in the upstream remote.

Exercise 5: Add a new file

We will add a file about you into the exercise_files/about_mes directory. You can copy the example already in the directory.

1. Update your local copies of upstream and origin, as well as your origin remote.
2. Create a new development branch.
3. Create a .txt file named your_name.txt. Fill the file with some basic information about yourself.
4. Check git status to see what it looks like to add an "untracked file" (a file that Git has never seen before).
5. Stage your file.
6. Commit your file.
7. Push your local change to your origin remote.
8. Open a pull request in the upstream remote.

Exercise 6: Viewing another contributor's changes

Notice all the changes that show up in the roster, favorite things document, and about me directory when you update your local repositories with the changes from upstream. We will look at those changes and make comments on our colleagues' favorite things.

1. Update your local copies of upstream and origin, as well as your origin remote.
2. Create a new development branch.
3. Open up exercise_files/favorite_things.md. Find two interesting favorite things to comment on and add those comments to the document. Examples: "Wow I like that too!" "That is a horrible opinion!" "My sister's dentist's son's girlfriend is really into this."
4. Stage your changes.
5. Commit your changes.
6. Push your local changes to your origin remote.
7. Open a pull request in the upstream remote.

Exercise 7: Responding to PR reviews

Sometimes, a maintainer of a repo will review your PR and ask you for changes. In this exercise, we will populate a document with a research question about anything you are curious about, and you will respond to my "changes requested."

1. Update your local copies of upstream and origin, as well as your origin remote.

2. Create a new development branch.

3. Open up exercise_files/research.md. Add your research question to the list.

4. Stage your changes.

5. Commit your changes.

6. Push your local changes to your origin remote.

7. Open a pull request in the upstream remote.

8. Request a review from me (@quinnylee). Click on the gear icon in the top right by "Reviewers" and select my username. It will look something like this:

   

9. When you see my "changes requested," go back to your working directory and make the appropriate change.

10. Stage your changes.

11. Commit your changes.

12. Push your local changes to your origin remote.

13. Check back on the PR page in the upstream remote. You should see that any changes you made to the origin remote are reflected in the commit history here too.

Exercise 8: Making your own repository

It's time for you to make your own repository. This repository will highlight your favorite place on your college's campus.

1. On the GitHub home page, click on the new repository button. It is a green button in the top left with a book icon.

   

2. Fill out the repository information. The owner is you, the repository name can be something like my-favorite-place, give it a short description, set visibility to public. Don't use a template, and don't add any of the files listed (README, .gitignore, license) for this exercise.

   

3. Click "Create repository".

4. Go to the location in your working directory where you want your local my-favorite-place repository to be located. Create a directory there.

   cd /path/to/dir
   mkdir my-favorite-place

5. On the GitHub website, there should be some instructions on how to create a new repository on the command line. Follow those instructions. You have created your repository!

Exercise 9: Stashing changes

It's good practice to do all your development work in a specific development branch. What do you do if you realize you've been doing work in the main branch?

1. Edit the README.md in your favorite place repository. Add some facts about the place and why you like it.

2. You've just realized you've been editing in main! We can store those changes while you switch to another branch.

   git stash

3. Your changes have been tucked away for now. Create a development branch and check it out.

4. Pull your previous changes back from the stash.

   git stash pop

5. Stage your changes.

6. Commit your changes.

Exercise 10: Amending commits and a bonus Vim lesson

Sometimes, you will want to edit the contents of a commit. This is super easy when you haven't pushed your local commits up to the remote yet. Let's add a picture of the location to the repository.

1. Download a photo of the location and put it in your repository.

2. Stage your changes.

3. Edit your commit.

   git commit --amend

   When you amend a commit, you will have an opportunity to amend your commit message. However, Git defaults to using the Vim editor for this action. Vim is a terminal-based, keyboard-only text editor that has some strange commands. However, if you learn Vim, these once-unintuitive commands become like second nature. See the subheading below for some Vim tips.

4. Push your local changes up to the remote.

Your bonus Vim lesson

You can navigate around the editor with your arrow keys, but the preferred Vim way is to use h for left, j for down, k for up, and l for right. Once you reach the spot you want to edit, press i to bring you to "insert mode". You can type as normal now. Once you are done editing, press esc to enter "normal mode." To save and exit, type in :wq (write, quit).

If you want to learn more Vim, vimtutor is a great tool!

vimtutor

Exercise 11: Reverting commits & git log

What happens if you accidentally commit and push something you didn't mean to publish?

1. We'll stay in the development branch you've been working in. Edit your README.md to add some lines about your least favorite place on campus.

2. Stage your changes.

3. Commit your changes.

4. Push your changes to the remote.

5. Let's revert this commit. First, we need the commit ID of the most recent commit.

   git log

6. Copy the commit hash of the commit where you made comments about your least favorite place. The commit hash is a long string of lots of letters and numbers.

7. Revert the commit.

   git revert <commit-hash>

   This will open another Vim-like editor to confirm a commit message. What Git is doing is creating a new commit that performs the opposite of your original changes.

8. Push this commit to the remote.

Exercise 12: Resetting commits

Okay, you accidentally committed a mistake but didn't push. How do you quickly fix this? We'll look at a couple options that git reset gives you.

1. Stay in the development branch you've been working in. Edit your README.md again to add some lines about your least favorite place on campus.

2. Stage your changes.

3. Commit your changes.

4. Reset your commit but keep your changes staged.

   git reset --soft HEAD~1

   --soft keeps your commit in the staging environment. HEAD~1 means to move the "head" of the branch back by 1 commit. Notice that if you use git status, your README.md is still staged.

5. Commit your change again.

6. Reset your commit and unstage it.

   git reset HEAD~1

   Notice that your changes are still in your working directory, but git status shows that they are unstaged.

7. Commit your change again.

8. Reset your commit and delete all code changes.

   git reset --hard HEAD~1

   Notice that your changes are gone entirely.

Exercise 13: Removing files

You now want your repository to be text-only. Let's remove the picture.

1. Remove the picture.

   git rm path/to/image

2. Commit the change.

3. Push the commit to your remote.

Exercise 14: Merging your own changes

Time to merge this development branch into main.

1. Go to your remote's GitHub page and create a PR that merges your development branch into main.
2. Merge the pull request.

Exercise 15: Making changes in someone else's repo (again)

This exercise will tee us up for the next one. You will suggest a change in one of your colleague's favorite place repository.

1. Find one of your colleague's repositories and fork it.
2. Clone your fork (remember to use the SSH URL).
3. Add your colleague's repository as the upstream remote.
4. Create and check out a local development branch.
5. Add a file saying something nice about the place that your colleague chose.
6. Stage your changes.
7. Commit your changes.
8. Push your commits to the origin remote.
9. Open a PR in the upstream remote.

Exercise 16: Merging someone else's changes

When someone makes a PR in your repo, you will have a chance to review it, suggest changes, make comments, ask questions, and ultimately decide to accept it or reject it. In this exercise, we will merge your colleague's comments about your favorite place.

1. Navigate to the PR that your colleague has opened in your repo.
2. Review the "files changed" tab.
3. Make a comment in the PR.
4. Merge the PR.

Exercise 17: Opening an issue

Issues are a neat way to make maintainers aware of bugs or feature requests. You can make an issue in basically any repository that is visible to you. In this exercise, we will make an issue in our own favorite things repo.

1. In your repo's GitHub page, go to the "Issues" tab and click "New issue."
2. Write an issue about wanting an image of the favorite place.
3. Publish the issue. Note the number that it is assigned. These numbers are how GitHub tracks issues and PRs.

Exercise 18: Closing an issue via PR

Issues are nice because they can be tied to PRs, which is a good way to track your development work. We will re-add the photo that you rm'ed earlier.

1. Update your local copies of upstream and origin, as well as your origin remote.
2. Create and check out a development branch.
3. Add the image of your favorite place to the repository.
4. Stage your change.
5. Commit your change.
6. Push your change to your remote.
7. Open a PR to merge the development branch into main. In the text description of the PR, you can write something like "Closes #[the number of the issue]".
8. Merge the PR. Notice that with the keyword "closes," the issue is automatically closed.

Other such keywords are "close, closed, fix, fixes, fixed, resolve, resolves, resolved."

Exercise 19: .gitignore

Sometimes, in software development, running code produces files that you don't want to publish. It is annoying to manually tell Git not to push those files to a remote. This is where a file called a .gitignore comes in handy.

1. Update your local copies of upstream and origin, as well as your origin remote.
2. Create and check out a development branch.
3. Add a stock photo of your college to the repository.
4. Add a file named .gitignore to the repository.
5. Put the filepath to the stock photo in the .gitignore.
6. Stage your changes.
7. Look at what was staged using git status. Notice that the stock photo did not get staged for commit!
8. Commit your changes.

Exercise 20: Other useful files to keep in a repository

Another useful file is a license. Licenses tell others what they are and aren't allowed to do with your code. Choosealicense.com is a site that contains the text of several common open-source licenses. For this exercise, we will add an MIT License, which is the most permissive license.

1. Add a file named LICENSE to your repository.
2. Copy the text of the MIT License from choosealicense into the LICENSE file.
3. Stage your changes.
4. Commit your changes.

Exercise 21: git diff

What do you do if you've made changes to a file, had to leave in the middle, came back, and forgot what you have done since your stage?

1. Add some text to your README.md that indicates that this repository was for a workshop in your REU.

2. See the differences between your working directory and what has already been staged.

   git diff

   You should see that the lines about the REU are highlighted in the diff.

3. Stage your changes.

4. Commit your changes.

5. Push your changes to your remote.

6. Open a PR in your remote to merge your development branch into main.

7. Merge your PR.

The end??

If you made it this far during the workshop, congrats! Now go help a colleague or do some vimtutor.