diff --git a/labs/b9.md b/labs/b9.md index 3ba27fb4..cf07a34f 100644 --- a/labs/b9.md +++ b/labs/b9.md @@ -18,8 +18,11 @@ version control! ### Pulling the code -If you haven't already cloned the decal-lab git repository, run: `git clone -https://github.com/0xcf/decal-labs.git` +If you haven't already cloned the decal-lab git repository, run: + +```sh +$ git clone https://github.com/0xcf/decal-labs.git +``` Go to your `decal-labs` directory and `cd` into the folder `b9`. Run `git pull` to pull the latest changes. @@ -44,16 +47,14 @@ program. At the moment, it takes one positional argument of either `coin` or flip/roll more than once. The `dice` argument doesn't work as we haven't implemented it yet, but you can try flipping a coin: -``` -exiang@supernova:~/decal-labs/b9$ python3 rand.py coin +```sh +~/decal-labs/b9$ python3 rand.py coin 1 coin flip(s) resulted in 0 Heads and 1 Tails: T - -exiang@supernova:~/decal-labs/b9$ python3 rand.py coin -i 10 +~/decal-labs/b9$ python3 rand.py coin -i 10 10 coin flip(s) resulted in 3 Heads and 7 Tails: T, T, H, T, H, H, T, T, T, T - -exiang@supernova:~/decal-labs/b9$ python3 rand.py coin -i 999 +~/decal-labs/b9$ python3 rand.py coin -i 999 Number of flips must be in the range [0 - 100] ``` @@ -74,17 +75,17 @@ mostly bug-free and stable). Let's make a branch for our dice rolling feature: -``` -git checkout -b dice +```sh +$ git checkout -b dice ``` This makes a new local branch called `dice` based on the branch that we are currently on (`master`) and switches you to the `dice` branch. This command is basically shorthand for: -``` -git branch dice // Create new branch called 'dice' -git checkout dice // Switch to branch called 'dice' +```sh +$ git branch dice # Create new branch called 'dice' +$ git checkout dice # Switch to branch called 'dice' ``` You can view the branches you've created by typing `git branch`. You should see @@ -93,26 +94,26 @@ asterisk is placed next to the branch that you've currently checked out. > You can make `git branch` (and many other command-line tools) display more > information by passing the verbose flag `-v`, or make it display even more -> information by adding additional `v` characters to the flag (e.g. `-vv`). `git -> branch -v` will display the commit message of the most recent commit on the -> branch (aka the `HEAD`). `git branch -vv` also displays in square brackets the -> remote branch that the local branch is tracking, if one exists. In this -> repository, `master` is associated with a remote branch `origin/master` that -> lives on Github's servers. This means when you `git push` or `pull` to/from +> information by adding additional `v` characters to the flag (e.g. `-vv`). For +> example, `git branch -v` will display the commit message of the most recent +> commit on the branch (aka the `HEAD`). `git branch -vv` also displays in square +> brackets the remote branch that the local branch is tracking, if one exists. +> In this repository, `master` is associated with a remote branch `origin/master` +> that lives on Github's servers. This means when you `git push` or `pull` to/from > `origin master`, you are syncing up your local copy of the `master` branch > with the remote `master` branch on Github's servers. At the moment, your newly -> created `dice` branch is local only, meaning that attempting to `git push` or -> `pull` will not work (or Git may ask you if you want to have a remote branch -> created). +> created `dice` branch is local only, meaning that it is not tracked. +> Therefore attempting to `git push` or `git pull` will not work (or Git may ask +> if you want to have a remote branch created). #### Making commits -Now that you're on your `dice` branch, you can safely start adding code without -modifying the `master` branch. The code for dice rolling will be split up into -three commits so that we can demonstrate how to combine multiple commits into a -single commit later. Open `rand.py` in your preferred text editor. Find the -comment in the `__main__` function that says `COMMIT 1` and add the following -code below it like so: +Now that you've created and swapped to the `dice` branch, you can safely start +adding code *without* modifying the `master` branch. The code for dice rolling +will be split up into three commits so that we can demonstrate how to combine +multiple commits into a single commit later. Open `rand.py` in your preferred +text editor. Find the comment in the `__main__` function that says `COMMIT 1` +and add the following code below it like so: ```python # COMMIT 1: Add -s flag for number of sides on a die @@ -126,7 +127,7 @@ code below it like so: ``` > If you're unsure about copying the code correctly, take a look at -`rand_reference.py` for what the finished code should look like! +> `rand_reference.py` for what the finished code should look like! Save and exit the text editor and return to the terminal. Type `git status` to see that `rand.py` has been changed but not staged. Type `git add rand.py` to @@ -146,12 +147,12 @@ Now, lets commit our changes and write a concise and useful commit message. Type companies will have different best practices for writing commit messages, but here are some common guidelines: -- Keep it short. Typical commits should be one line (some exceptions). If a lot - of changes have been made, you might want to make multiple commits instead. +- **Keep it short.** Typical commits should be one line (some exceptions). If a + lot of changes have been made, you might want to make multiple commits instead. -- Make it descriptive. If someone needs to read the commit history, they're not - going to know or remember what was changed by a commit that just says "Fixed - bug" or "WIP". +- **Make it descriptive.** If someone needs to read the commit history, they're + not going to know or remember what was changed by a commit that just says + "Fixed bug" or "WIP". - A lot of places like to capitalize the first letter and use the "\ \" sentence structure. For example, "Add", @@ -198,8 +199,8 @@ following code. Then stage your changes and make a commit with the message When you're done, you should now be able to roll dice: -``` -exiang@supernova:~/decal-labs/b9$ python3 rand.py dice -i 10 -s 20 +```sh +~/decal-labs/b9$ python3 rand.py dice -i 10 -s 20 10 roll(s) of a 20-sided die resulted in a sum of 119: 15, 3, 12, 10, 16, 8, 18, 20, 13, 4 ``` @@ -208,11 +209,11 @@ exiang@supernova:~/decal-labs/b9$ python3 rand.py dice -i 10 -s 20 Let's take a look at the commits you've made. Type `git log` to see a history of commits. Each commit has some information such as who authored the commit, a -timestamp for when the commit was created, and the commit message. +timestamp for when the commit was created, and the commit message. - The first line of each commit entry has a long hexadecimal string. This is the commit *hash*: think of it as a unique ID that you can use to reference that - specific commit. + specific commit. - Some commits have branch information in parentheses next to the commit hash, indicating that they are the most recent commit or `HEAD` of that branch. Your @@ -230,26 +231,26 @@ difference between two commits. There are a few different ways you can reference a commit. One that was mentioned before was copying a commit's hash (note that your commit hashes will be different from the example below): -``` -git diff 3368313c0afb6e306133d604ca72b0287124e8f2 762053064506810dee895219e5b2c2747a202829 +```sh +$ git diff 3368313c0afb6e306133d604ca72b0287124e8f2 762053064506810dee895219e5b2c2747a202829 ``` You can also copy a small chunk of the beginning of the commit hash instead of the entire hash. Because of the way hashes work, it's very unlikely that you'll have two commits that have the exact same starting sequence. -``` -git diff 3368313 7620530 +```sh +$ git diff 3368313 7620530 ``` If you're trying to `diff` two commits that are pretty close together in the log, an easier way is to reference commits by their distance from the `HEAD` -(most recent) commmit using the format `HEAD~`. Since we added three +(most recent) commit using the format `HEAD~`. Since we added three commits new commits in `dice`, we can view the difference between `dice` and `master` using the following command: -``` -git diff HEAD~3 HEAD +```sh +$ git diff HEAD~3 HEAD ``` #### Merge conflicts and `rebase` @@ -257,12 +258,13 @@ git diff HEAD~3 HEAD Now that you've implemented dice rolling on on your feature branch, you'll want to merge your feature into the `master` branch. This means that Git will take your changes on the `dice` branch and and replay them on the `master` branch, -bringing `master` up to date with `dice`. However, things can go wrong when -`master` has new commits added to it while you're working on `dice`. Now, our -commits on `dice` may be based on an old version of master. Even worse, someone -else may have modified the same lines of code on `master` that we changed on -`dice`, resulting in Git not knowing whose lines to use. This is called a *merge -conflict*. +bringing `master` up to date with `dice`. However, things can ([and often will]( +https://en.wikipedia.org/wiki/Murphy%27s_law)) go wrong when `master` has new +commits added to it while you're working on `dice`. Now, our commits on `dice` +may be based on an old version of master. Even worse, someone else may have +modified the same lines of code on `master` that we changed on `dice`, +resulting in Git not knowing whose lines to use. This is called a *merge +conflict*. Let's simulate a merge conflict by making a change on `master`. **Switch to the `master` branch using `git checkout master`.** Make sure that you're on the @@ -350,7 +352,7 @@ check below. 1. On your `master` branch, type `git log` and paste a portion of your commit history showing the commit(s) you merged in from your `dice` branch plus a few commits into the past for context. If you haven't completed the optional - "Combining commists" section, 5-6 of the most recent commits should be + "Combining commits" section, 5-6 of the most recent commits should be sufficient. If you have completed the optional section and squashed your commits, 3-4 of the most recent commits should be sufficient. @@ -365,19 +367,19 @@ check below. Git has the ability to combine multiple commits into a single commit. This process is called squashing. You may want to do this if you have work in progress commits that you want to combine into a single finished commit, or in -our case, keeping `git log` for the `master` branch more digestable. +our case, keeping `git log` for the `master` branch more digestible. - Pros: If you have a feature branch with fifty commits, you prevent inundating `master`'s history with fifty different commits when merging. When you squash, you can make a multi-line commit message where the first line is a summary of the feature, and subsequent lines are bullet points containing relevant - individual commit messages from the individaul commits. + individual commit messages from the individual commits. - Cons: You lose the granularity of the history on `master`, making it more difficult if you want to partially roll back your feature. Git also doesn't support having multiple authors for a single commit, so if you want to credit other contributors you need to add co-author credit somewhere in the commit - message of your combined commit. + message of your combined commit. Aside: you can see how co-authoring works with GitHub [here](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors#creating-co-authored-commits-on-the-command-line). **First, make sure you're on your `dice` branch using `git checkout dice`.** We will be performing our squash using the command `git rebase` in interactive mode @@ -404,15 +406,14 @@ hashes and likely a different commit message on the first line than the example below: ``` -pick 9f785bc Remove trailing whitespace +pick 7c5bd5d fixed sus pick 1f7a1e1 dice rolling WIP pick 26e0827 Add -s flag for number of sides on a die pick b193d44 Add dice rolling logic and output dice sum and sequence pick 554402e Restrict input range for dice iterations and sides # Rebase 7dac858..554402e onto b193d44 (5 commands) -# -... +# ... ``` As you can see, Git includes useful instructions on what you can do with commits @@ -421,20 +422,19 @@ can combine, delete, reword, or even reorder our commits, along with many more options. In our case, we want to `squash` our two most recent commits into the third most recent commit in the list. To do this, replace the word `pick` with the word `squash` (or just `s` for short) on the *last two lines*. *Do not -`squash` the third line*; that will take your three most recent commmits and +`squash` the third line*; that will take your three most recent commits and meld them with the "dice rolling WIP" commit, which is a commit from `master`. Your file should look something like this: ``` -pick 9f785bc Remove trailing whitespace +pick 7c5bd5d fixed sus pick 1f7a1e1 dice rolling WIP pick 26e0827 Add -s flag for number of sides on a die squash b193d44 Add dice rolling logic and output dice sum and sequence squash 554402e Restrict input range for dice iterations and sides # Rebase 7dac858..554402e onto b193d44 (5 commands) -# -... +# ... ``` Save and exit the file. Git will now rewrite the commit history as you @@ -471,12 +471,12 @@ Add dice roll feature Save the file and exit. The rebase is now complete! Type `git log` and view your new squashed commit. If you didn't already merge your three individual commits -into `master`, you can run `git merge master` to merge in your combined commit. +into `master`, you can run `git merge master` to merge in your combined commit. ``` -commit c0fa61ad59a76635701813472bfbc1c7f36bb857 (HEAD -> dice) -Author: Edric Xiang -Date: Wed Aug 12 19:00:29 2020 -0700 +commit 6b4f705921f9b06af880f97d36cb0b74e51aeb0c (HEAD -> dice) +Author: Max Vogel +Date: Sun Apr 3 19:45:51 2022 -0700 Add dice roll feature @@ -500,7 +500,7 @@ repository that can be reviewed by others, commented on, and edited before the changes are actually approved to be merged into the repository. For example, when working on a large project with a team, you may want to submit a pull request with your new feature so that team members can review your code for bugs -or code style mistakes. For projects on public repostitories that invite +or code style mistakes. For projects on public repositories that invite contributions from strangers, you can contribute a feature by forking the repository (making a copy of it that you own), implementing your feature, and then making a pull request to have your contribution merged into the official @@ -509,7 +509,7 @@ repository. First, read up on [how to create a pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) from Github's documentation. We've created a dummy repository at -https://github.com/0xcf/decal-pr-practice for you to practice making a simple PR +[github.com/0xcf/decal-pr-practice](https://github.com/0xcf/decal-pr-practice) for you to practice making a simple PR from a fork. You will be making a fork of the repo, writing your name in the Markdown file in the repo, and then making a PR to merge your change into the original repo. @@ -517,7 +517,7 @@ original repo. 1. Read about [how to fork a repo](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) from Github's documentation. Make a fork of our dummy repository at - https://github.com/0xcf/decal-pr-practice. + [github.com/0xcf/decal-pr-practice](https://github.com/0xcf/decal-pr-practice). 2. Clone your forked repository and create a new branch based on `master` called `my-name`. Open `README.md` and replace "Tux the Penguin" with your name. @@ -534,7 +534,7 @@ original repo. You've now made a pull request! Github has a lot of features for pull requests, feel free to check some of them out. This lab you're reading right now was merged through a PR, which you can view at -https://github.com/0xcf/decal-web/pull/216. +[github.com/0xcf/decal-web/pull/216](https://github.com/0xcf/decal-web/pull/216). - The main page for the pull request has a timeline of commits and any comments from reviewers. PRs can be continually updated by making and pushing new @@ -547,8 +547,8 @@ https://github.com/0xcf/decal-web/pull/216. other people to review your changes, assign others to work on the PR, and link an issue that your PR will resolve if it gets merged. Github repositories have an "Issues" tab where one can submit a report about a bug or request a feature - (e.g. https://github.com/0xcf/decal-web/issues). The Github issue associated - with the PR for this lab is at https://github.com/0xcf/decal-web/issues/184. + (e.g. [github.com/0xcf/decal-web/issues](https://github.com/0xcf/decal-web/issues)). The Github issue associated + with the PR for this lab is at [github.com/0xcf/decal-web/issues/184](https://github.com/0xcf/decal-web/issues/184). - Go to the "Files Changed" tab to see a diff of the PR's changes. Reviewers of your PR can leave inline comments on a specific line of code by hovering over @@ -563,8 +563,8 @@ checked off for completion. 2. Why does Git require us to manually intervene in merge conflicts? -3. What command would you use to sync a folder ~/Downloads/Linux_ISOs to the - folder /usr/local/share/Calendar, while preserving file metadata? (hint: use +3. What command would you use to sync a folder `~/Downloads/Linux_ISOs` to the + folder `/usr/local/share/Calendar`, while preserving file metadata? (hint: use rsync) 5. How does rsync determine when to look for changes between files? Select from @@ -580,6 +580,6 @@ checked off for completion. E. By seeing if the permissions of the files are different. -6. Consider a file str1 containing the string 'abcd'. You rsync it to another - file str2, and then replace 'abcd' with 'aaaa' on str1. If you run 'rsync - --append str1 str2', what will the contents of str2 be? +6. Consider a file `str1` containing the string 'abcd'. You rsync it to another + file `str2`, and then replace 'abcd' with 'aaaa' on str1. If you run `rsync + --append str1 str2`, what will the contents of str2 be?