From 8e2c478703f2a03ac84839e3317fb5c3e5b6ee08 Mon Sep 17 00:00:00 2001 From: Ching Tong Date: Mon, 19 Sep 2022 09:34:58 -0400 Subject: [PATCH 01/10] Cleaning up and changing content for more collaborative class material --- README.md | 43 ++++++++++++++------------ favorite-animals/ching_tong.py | 1 + favorite-animals/evilardvark.py | 1 - favorite-animals/example_script.py | 1 - favorite-animals/goldie_locks.py | 1 - favorite-animals/grayson_fattaleh.py | 1 - favorite-animals/hayden_fav_animal.py | 1 - favorite-animals/jonah_duffin.py | 1 - favorite-animals/micah_pixton.py | 1 - favorite-animals/mike_tyson.py | 1 - favorite-animals/nathan_harker.py | 1 - favorite-animals/stephen_godderidge.py | 1 - mike_tyson.py | 2 -- 13 files changed, 25 insertions(+), 31 deletions(-) create mode 100644 favorite-animals/ching_tong.py delete mode 100644 favorite-animals/evilardvark.py delete mode 100644 favorite-animals/example_script.py delete mode 100644 favorite-animals/goldie_locks.py delete mode 100644 favorite-animals/grayson_fattaleh.py delete mode 100644 favorite-animals/hayden_fav_animal.py delete mode 100644 favorite-animals/jonah_duffin.py delete mode 100644 favorite-animals/micah_pixton.py delete mode 100644 favorite-animals/mike_tyson.py delete mode 100644 favorite-animals/nathan_harker.py delete mode 100644 favorite-animals/stephen_godderidge.py delete mode 100644 mike_tyson.py diff --git a/README.md b/README.md index 1ff678d..5e64dca 100644 --- a/README.md +++ b/README.md @@ -52,45 +52,49 @@ You'll need to clone your fork repository to your local environment. "Clone" mig And Voila! You've officially cloned the repository onto your local machine. Navigate to your repository by running a quick `cd learn-git` -### Step 2.5: Adding a "Remote" back to the original repository + ## Step 3: Create a feature branch on your local repo -Now that you're on your local repository, you can focus on making our changes. Your assignment is to add a script to the `favorite-animals/` directory. Yes, very complicated. It's basic, but the goal is to learn git. You'll name your script `your_firstname_and_lastname.py`, commit it to your local repo, push your changes to your fork, and open a repo. Phew, that's a lot! Don't worry, you'll focus on creating the feature branch in this step. +Now that you're on your local repository, you can focus on making our changes. Your assignment is to create a folder, all contribute to the same file, and manage any merge conflicts. Yes, very complicated. It's basic, but the goal is to learn git. You'll create a folder with a name of your choice with a `.py` file inside. Feel free to name your script whatever you want, commit it to your local repo, push your changes to your fork, and open a repo. Phew, that's a lot! Don't worry, you'll focus on creating the feature branch in this step. 1. Make sure you're in the root of your local repo. Use `cd` to get there. To make sure you're on the master branch, run `git status`. The output will show you your current branch. If you're not on your default branch, run the command in step three to switch back. We'll come back to `git status` in a minute. > (Feature) Branch: A git branch is like an alternate history for your code. In most repositories the branch where your working version lives is called something like `master`, `main`, or `prod`. If you want to try out some changes or build a new feature, you can create a new branch to ensure the other branches of your code won't be affected. When you are ready to add your feature back to the working version you _merge_ the feature branch into `master`. -2. Run `git branch my-animal`. This creates a snapshot (a branch) of your current branch (`master` in this case) named `my-animal`. You could have named this branch whatever you'd like (ex: `git branch covid-sucks`). In this case, you'll be adding our simple script to this branch. +2. Run `git branch {any-branch-name}`. This creates a snapshot (a branch) of your current branch (`master` in this case) named `{any-branch-name}`. You could have named this branch whatever you'd like (ex: `git branch covid-sucks`). In this case, you'll be adding our simple script to this branch. -3. Now that you have our new branch created, you need to switch our current branch to the new branch. You refer to this process of branch switching as "checking out a branch." Run `git checkout my-animal`. Now, run `git status` to confirm that the current branch as `my-animal`. +3. Now that you have our new branch created, you need to switch our current branch to the new branch. You refer to this process of branch switching as "checking out a branch." Run `git checkout {any-branch-name}`. Now, run `git status` to confirm that the current branch as `{any-branch-name}`. -4. BONUS - in the future, when you create branches, you can use `git checkout -b ` as a shortcut to `git branch` and `git checkout`. This is the same thing as running `git branch my-animal && git checkout my-anmial`. Personally, I _always_ use `git checkout -b`. +4. BONUS - in the future, when you create branches, you can use `git checkout -b {insert-branch-name}` as a shortcut to `git branch` and `git checkout`. This is the same thing as running `git branch {any-branch-name} && git checkout {any-branch-name}`. Personally, I _always_ use `git checkout -b`. And voila! You've created your feature branch. You're all set to make these changes. -## Step 4: Add a Python script +## Step 4: Add a folder structure and upload to your repository In this step, you're going to add a script. The important part is that you're going to make changes locally, commit those changes to our feature branch, and ultimately you'll be pushing these changes to our fork. +Before we jump in. Everyone in your group number off from 1-4. We will be splitting up work to make it more collaborative and experience how it feels to contribute to the same repo as your group. + +Person 1: 1. Open the `learn-git` folder in your code editor. -2. Add a new file to the `favorite-animals/` folder. -3. Name this file `.py`. Example: stephen_godderidge.py -4. Add a print statement to the file. This could be anything you want. If you'd like to play along, add a statement that describes your favorite animal. My script does the following: -```python -print("My favorite animals are sloths") -``` -5. Save your new file. +2. Add a new folder with a name of your choice. +3. Create a file and name it whatever you may like. Example: i_love_code.py Now you're ready to move on and actually commit your changes! + + ## Step 5: Commit your changes Committing your changes adds your changes to the current branch. Before you commit your changes, you have to _stage_ your changes. This step may seem trivial when you're working on a few files (especially in our case), but this step becomes more helpful as you work on more files at once. @@ -98,23 +102,24 @@ Committing your changes adds your changes to the current branch. Before you comm Think of committing your staged changes as saving your changes to your repository. Follow the steps below, and we'll come back to this question. -1. Make sure you saved your new script. +Person 1: +1. Make sure you saved your new empty file. -2. Run `git status` to see the files that have been changed. You should see a `Changes not staged for commit:` section. Underneath, you should see the file path to your new script (example: `favorite-animals/stephen_godderidge.py`). These are changes that you have saved to your files, but they aren't currently setup to be committed yet. _Your changes aren't staged yet_. In fact, you'll need _add_ them to the staged files before you can commit them. +2. Run `git status` to see the files that have been changed. You should see a `Changes not staged for commit:` section. Underneath, you should see the file path to your new script. These are changes that you have saved to your files, but they aren't currently setup to be committed yet. _Your changes aren't staged yet_. In fact, you'll need _add_ them to the staged files before you can commit them. -3. Run `git add favorite-animals/.py`. This step adds the file to the files staged for the commit. +3. Run `git add {insert_your_folder_name}/{insert_your_script_name}.py`. This step adds the file to the files staged for the commit. > Note -- if you'd like to stage all of the files you've made changes to locally, you can simply run the shortcut `git add .` instead of adding each file individually. 4. Run `git status` again to confirm the changes have been added to the staged files. You should see a `Changes to be committed:` section. Underneath, you should see the new file path. This means your files are ready to be committed. -5. Run `git commit -m "add my new script"`. This commits the changes, and allows us to add a git commit message at the same time. Now, our branch has been updated to point to this new commit. +5. Run `git commit -m "add my new folder/file"`. This commits the changes, and allows us to add a git commit message at the same time. Now, our branch has been updated to point to this new commit. 6. Run `git status` to check that the files have been added. You should see a message that says `nothing to commit, working tree clean` And voila! You've committed your changes. -Now, back to the question – _How is saving your files on your computer different from committing your changes to your repository?_ Committing your changes bundles all of your changes into a single commit and adds that commit to your branch. Once your branch includes this new commit, you are able to push your changes up to your remote repository. From there, someone else could pull your changes, create a branch from your branch, and start adding new commits. By stringing these commits together, the repository has an accurate view of the current state of the branch. +Now, back to the question – _How is saving your files on your computer different from committing your changes to your repository?_ Committing your changes bundles all of your changes into a single commit and adds that commit to your branch. Once your branch includes this new commit, you are able to push your changes up to your remote repository. From there, someone else could pull your changes, create a branch from your branch, and start adding new commits (not a spoiler alert at all). By stringing these commits together, the repository has an accurate view of the current state of the branch. Once you have several commits on a branch, you can choose to do a whole host of different actions - undo (wipe away the changes completely), unstage (un-commit the changes, and add them to the unstaged files on your local workspace), and more. diff --git a/favorite-animals/ching_tong.py b/favorite-animals/ching_tong.py new file mode 100644 index 0000000..fa0ce25 --- /dev/null +++ b/favorite-animals/ching_tong.py @@ -0,0 +1 @@ +print("My favorite animal is a dolphin, or maybe a dog") diff --git a/favorite-animals/evilardvark.py b/favorite-animals/evilardvark.py deleted file mode 100644 index 0f6ea39..0000000 --- a/favorite-animals/evilardvark.py +++ /dev/null @@ -1 +0,0 @@ -print("Advark wants to eat you") diff --git a/favorite-animals/example_script.py b/favorite-animals/example_script.py deleted file mode 100644 index 2278cef..0000000 --- a/favorite-animals/example_script.py +++ /dev/null @@ -1 +0,0 @@ -print("Orangutans are my favorite animals") diff --git a/favorite-animals/goldie_locks.py b/favorite-animals/goldie_locks.py deleted file mode 100644 index 44c2089..0000000 --- a/favorite-animals/goldie_locks.py +++ /dev/null @@ -1 +0,0 @@ -print("My favorite animals are bears") \ No newline at end of file diff --git a/favorite-animals/grayson_fattaleh.py b/favorite-animals/grayson_fattaleh.py deleted file mode 100644 index ae70768..0000000 --- a/favorite-animals/grayson_fattaleh.py +++ /dev/null @@ -1 +0,0 @@ -print(" Graysons favorite animal is a big dog.") \ No newline at end of file diff --git a/favorite-animals/hayden_fav_animal.py b/favorite-animals/hayden_fav_animal.py deleted file mode 100644 index 65469cf..0000000 --- a/favorite-animals/hayden_fav_animal.py +++ /dev/null @@ -1 +0,0 @@ -print('My fav animal is a cheetah') \ No newline at end of file diff --git a/favorite-animals/jonah_duffin.py b/favorite-animals/jonah_duffin.py deleted file mode 100644 index 5c0d73f..0000000 --- a/favorite-animals/jonah_duffin.py +++ /dev/null @@ -1 +0,0 @@ -print("My favorite animal is the hippopotamus") \ No newline at end of file diff --git a/favorite-animals/micah_pixton.py b/favorite-animals/micah_pixton.py deleted file mode 100644 index 6ce113e..0000000 --- a/favorite-animals/micah_pixton.py +++ /dev/null @@ -1 +0,0 @@ -print('My favorite animal is a bald eagle') \ No newline at end of file diff --git a/favorite-animals/mike_tyson.py b/favorite-animals/mike_tyson.py deleted file mode 100644 index 5ea5799..0000000 --- a/favorite-animals/mike_tyson.py +++ /dev/null @@ -1 +0,0 @@ -print("My favorite animal is a monkey") \ No newline at end of file diff --git a/favorite-animals/nathan_harker.py b/favorite-animals/nathan_harker.py deleted file mode 100644 index c260e09..0000000 --- a/favorite-animals/nathan_harker.py +++ /dev/null @@ -1 +0,0 @@ -print("COVID sucks") \ No newline at end of file diff --git a/favorite-animals/stephen_godderidge.py b/favorite-animals/stephen_godderidge.py deleted file mode 100644 index e1a79f6..0000000 --- a/favorite-animals/stephen_godderidge.py +++ /dev/null @@ -1 +0,0 @@ -print("Stephen's favorite Animals are a Donkey") \ No newline at end of file diff --git a/mike_tyson.py b/mike_tyson.py deleted file mode 100644 index 0d04e92..0000000 --- a/mike_tyson.py +++ /dev/null @@ -1,2 +0,0 @@ -print("My favorite animal is a monkey") -print('Yes it did work') \ No newline at end of file From 7f233cad70f8aa664c37f6e2e7861c6546d4b0ef Mon Sep 17 00:00:00 2001 From: Ching Tong Date: Mon, 19 Sep 2022 21:45:38 -0400 Subject: [PATCH 02/10] Adding more changes to the group assignment --- README.md | 41 +++++++++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 5e64dca..d8f5da3 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,13 @@ The README of this repo is the tutorial, but you'll use the rest of the files to In this tutorial, you will be doing the following steps: 1. Fork This Repository 2. Clone Your Newly-Created Fork +3. Give edit permissions to your group 3. Create a feature branch on your local repo -4. Add a python script to the `favorite-animals/` folders +4. Add a python script to a new folder 5. Commit your changes 6. Push your local feature branch to your remote repo (your fork) -7. Open a Pull Request to the Starting Repository (stephengodderidge/learn-git) +7. Pull down latest changes from master +8. All team members contribute to newly created repository ## Step 1: Fork This Repository @@ -62,8 +64,8 @@ One of the trickiest parts of Git is updating your local branch with the changes Congrats! You added your new remote! Now, when updates are added to that repository, we'll be able to _pull_ those changes to your local repository. We'll practice this after we open our pull request in the Bonus section of this tutorial. --> -## Step 3: Create a feature branch on your local repo -Now that you're on your local repository, you can focus on making our changes. Your assignment is to create a folder, all contribute to the same file, and manage any merge conflicts. Yes, very complicated. It's basic, but the goal is to learn git. You'll create a folder with a name of your choice with a `.py` file inside. Feel free to name your script whatever you want, commit it to your local repo, push your changes to your fork, and open a repo. Phew, that's a lot! Don't worry, you'll focus on creating the feature branch in this step. +## Step 4: Create a feature branch on your local repo +Now that you're on your local repository, you can focus on making our changes. Your assignment is to create a folder, add code to the same file, make pull requests, pull down latest changes, and manage any merge conflicts. Yes, very complicated. It's basic, but the goal is to learn git. You'll create a folder with a name of your choice with a `.py` file inside. Feel free to name your script whatever you want, commit it to your local repo, push your changes to your fork, and open a repo. Phew, that's a lot! Don't worry, you'll focus on creating the feature branch in this step. 1. Make sure you're in the root of your local repo. Use `cd` to get there. To make sure you're on the master branch, run `git status`. The output will show you your current branch. If you're not on your default branch, run the command in step three to switch back. We'll come back to `git status` in a minute. @@ -77,7 +79,7 @@ Now that you're on your local repository, you can focus on making our changes. Y And voila! You've created your feature branch. You're all set to make these changes. -## Step 4: Add a folder structure and upload to your repository +## Step 5: Add a folder structure and upload to your repository In this step, you're going to add a script. The important part is that you're going to make changes locally, commit those changes to our feature branch, and ultimately you'll be pushing these changes to our fork. Before we jump in. Everyone in your group number off from 1-4. We will be splitting up work to make it more collaborative and experience how it feels to contribute to the same repo as your group. @@ -95,7 +97,7 @@ print("My favorite animal is a dolphin") ``` 5. Save your new file. --> -## Step 5: Commit your changes +## Step 6: Commit your changes Committing your changes adds your changes to the current branch. Before you commit your changes, you have to _stage_ your changes. This step may seem trivial when you're working on a few files (especially in our case), but this step becomes more helpful as you work on more files at once. > Think of an assembly line that creates new cars. The cars are assembled, and they go to a separate location for a quality check before shipping out to the customer. This is what your staged changes are. You work on a bunch of changes locally, and then stage the changes (quality check) before they're finally committed (shipped to the customer). Once you've staged your changes, you can review your changes before finally committing them. @@ -103,7 +105,7 @@ Committing your changes adds your changes to the current branch. Before you comm Think of committing your staged changes as saving your changes to your repository. Follow the steps below, and we'll come back to this question. Person 1: -1. Make sure you saved your new empty file. +1. Make sure you saved your new empty `.py` file. 2. Run `git status` to see the files that have been changed. You should see a `Changes not staged for commit:` section. Underneath, you should see the file path to your new script. These are changes that you have saved to your files, but they aren't currently setup to be committed yet. _Your changes aren't staged yet_. In fact, you'll need _add_ them to the staged files before you can commit them. @@ -123,10 +125,13 @@ Now, back to the question – _How is saving your files on your computer differe Once you have several commits on a branch, you can choose to do a whole host of different actions - undo (wipe away the changes completely), unstage (un-commit the changes, and add them to the unstaged files on your local workspace), and more. -## Step 6: Push your local feature branch to your remote repo (your fork) +## Step 7: Push your local feature branch to your remote repo (your fork) Now that you have your changes committed, you need to _push_ those changes to your remote repository, which is a fork of the original `learn-git` repository. At the end of this step, your remote repository will include your feature branch. -1. Check which branch you're on by running `git status`. If you're not on your feature branch, go ahead and checkout that branch with `git checkout my-animal`. +1. Check which branch you're on by running `git status`. If you're not on your feature branch, go ahead and checkout that branch with `git checkout {insert-branch-name}`. + + > Note -- If you don't remember the name of your branch, you can run `git branch` in your terminal and it'll display all the branches you have locally. + 2. Run `git push`. Git should automatically display a message similar to: ``` The current branch my-animal has no upstream branch. @@ -137,10 +142,10 @@ Now that you have your changes committed, you need to _push_ those changes to yo ``` Don't worry, nothing is wrong. Git is simply helping us with your next step. Git is telling you that you need to set the upstream branch of your local branch to the remote copy (origin). Phew, that was a lot. Let's break it down. - So, what is `origin`? This is the term that git uses to refer to a remote repo. In our case, origin is our remote repository (our fork). The upstream branch is the branch tracked on the remote repository by your local branch. So, in our case, we're setting up our local `my-animal` branch to track any changes that happen in our origin's (our fork's) `my-animal` branch. When would this be useful? Well, say we have multiple developers making changes to a feature branch. We need a way to pull down the latest commits + So, what is `origin`? This is the term that git uses to refer to a remote repo. In our case, origin is our remote repository (our fork). The upstream branch is the branch tracked on the remote repository by your local branch. So, in our case, we're setting up our local branch to track any changes that happen in our origin's (our fork's) branch. When would this be useful? Well, say we have multiple developers making changes to a feature branch. We need a way to pull down the latest commits [More on that in this helpful article](https://devconnected.com/how-to-set-upstream-branch-on-git/#:~:text=Upstream%20branches%20define%20the%20branch,set%20upstream%20branches%20on%20Git.) -3. Do as git suggests and run `git push --set-upstream origin my-animal`. You'll see a bunch of update statements like `resolving deltas` and `Writing objects:`. This means git is pushing your local branch to your remote repo. You'll also see a helpful line that should read: +3. Do as git suggests and run `git push --set-upstream origin {insert-branch-name}`. You'll see a bunch of update statements like `resolving deltas` and `Writing objects:`. This means git is pushing your local branch to your remote repo. You'll also see a helpful line that should read something similar to this: ``` remote: Create a pull request for 'my-animal' on GitHub by visiting: @@ -151,20 +156,24 @@ Copy this URL. You're going to need it in a minute! 4. Bonus -- go to your fork in your browser. In the top left corner, you should see a button that says `Master`. Click it, and see that your branch is there. You can open you branch and navigate to your script. You should be able to see your changes. Pretty cool right? -## Step 7: Open a Pull Request to the Starting Repository (stephengodderidge/learn-git) -Our next goal is to add our commits to the master branch of the real `learn-git` repo so others can see our script and make changes if they'd like. In order to do this, you need to submit a request to pull those changes into the repo. In other words, you need to open a __pull request__. +## Step 8: Open a Pull Request + + Our next goal is to add our commits to the master branch of our newly created `learn-git` repo so others can see our script and make changes if they'd like. In order to do this, you need to submit a request to pull those changes into the repo. In other words, you need to open a __pull request__. This Pull Request needs to be approved by the owners of the repository before it can be _merged_ into master. Different companies have different approval processes (example: multiple reviewers from different teams), but our use case is simple. You're simply focused on opening the pull request. -1. Open a request by going to the link in the last step of Step 6. It should look like `https://github.com//learn-git/pull/new/my-animal`. This should take you to a page with the title of __Open a pull request__. +1. Open a request by going to the link in the last step of Step 6. It should look like `https://github.com//learn-git/pull/new/{insert-branch-name}`. This should take you to a page with the title of __Open a pull request__. 2. Name your Pull Request whatever you want. Add some comments if you'd like. 3. Once you've added your PR name and comments, go ahead and click the `Create Pull Request`. Congrats! You've opened your first pull request!! Go ahead and take a look around at the different tabs. See if you can find where you can view your changes (Hint: look for files). You can also view your commit(s). -Because you don't own the upstream repo (`stephengodderidge/learn-git`), you won't be able to approve your own PR. I'll keep an eye on this repo, and once I see your PR, I'll approve it and merge it into master. +## Step 9: Approve a Pull Request + +Now that the pull request has been created, it needs to be reviewed, approved, and merged into our `master` branch. + +Since Person 1 has given edit permissions to the whole group. Let's have the person with the nearest birthday in the remaining group (Person 2, 3, or 4) be the approver. -Note that if I wanted to, I could add collaborators that contribute directly to this repository by going to Settings -> Manage Access -> Invite a Collaborators. This would be particularly useful for group projects. # And We've finished the Tutorial! Pat yourself on the back, you're well on your way to mastering git From f5104e6fbdd523cf04f647491f4f68248e2d6aba Mon Sep 17 00:00:00 2001 From: Ching Tong Date: Mon, 19 Sep 2022 22:07:16 -0400 Subject: [PATCH 03/10] finishing up first pass changes to group assignment --- README.md | 44 ++++++++++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index d8f5da3..62ce359 100644 --- a/README.md +++ b/README.md @@ -54,16 +54,6 @@ You'll need to clone your fork repository to your local environment. "Clone" mig And Voila! You've officially cloned the repository onto your local machine. Navigate to your repository by running a quick `cd learn-git` - - - ## Step 4: Create a feature branch on your local repo Now that you're on your local repository, you can focus on making our changes. Your assignment is to create a folder, add code to the same file, make pull requests, pull down latest changes, and manage any merge conflicts. Yes, very complicated. It's basic, but the goal is to learn git. You'll create a folder with a name of your choice with a `.py` file inside. Feel free to name your script whatever you want, commit it to your local repo, push your changes to your fork, and open a repo. Phew, that's a lot! Don't worry, you'll focus on creating the feature branch in this step. @@ -91,12 +81,6 @@ Person 1: Now you're ready to move on and actually commit your changes! - - ## Step 6: Commit your changes Committing your changes adds your changes to the current branch. Before you commit your changes, you have to _stage_ your changes. This step may seem trivial when you're working on a few files (especially in our case), but this step becomes more helpful as you work on more files at once. @@ -172,11 +156,35 @@ Congrats! You've opened your first pull request!! Go ahead and take a look aroun Now that the pull request has been created, it needs to be reviewed, approved, and merged into our `master` branch. -Since Person 1 has given edit permissions to the whole group. Let's have the person with the nearest birthday in the remaining group (Person 2, 3, or 4) be the approver. +Since Person 1 has given edit permissions to the whole group and they cannot approve their own pull request. Let's have the person with the nearest birthday in the remaining group (Person 2, 3, or 4) be the approver. + +1. Navigate to the Pull Requests tab on GitHub, the url should look something like `https://github.com//learn-git/pulls` +2. Navigate to Files Changed tab +3. Click Review Changes, click `Approve` radio button, and add a comment if you would like, and press submit! + >Note -- It is not good practice to approve a pull request without thoroughly reading over the code and ensuring that what we are putting into master is good code. However, since this tutorial is focused more on git principles rather than coding principles, don't stress too much about mulling over the one line print statement. +4. Once the pull request has been approved, Person 1 can go ahead and merge the pull request. + + +Ta daaaa! You have now reviewed a PR, approved the code, and now the code exists in master! We want the whole team to be able to try this whole process that we walked through. + +## Step 10: Rinse and Repeat + +Starting with Person 4 and going backwards, you will now repeat the steps we just walked through. This is your time to collaborate together and try to remember what we have learned so far. +1. Pull down the latest code in master +2. Add a print statement to your `.py` file. This can be anything you want. You can share your favorite joke, animal, etc. An example could be: + + ```python + print("My favorite animal is a dolphin") + ``` +3. Save your file and make a commit containing your changes +4. Create a pull request +5. Ask a group member to approve your pull request +6. Merge your request. +7. Repeat until all group members have contributed to your repo. -# And We've finished the Tutorial! Pat yourself on the back, you're well on your way to mastering git +# And We've finished the Tutorial! Pat yourself on the back, you're well on your way to mastering git. If you have spare time, consider trying to manage a merge conflict, rebasing your pull request instead of merging, or reverting a commit. ## More Content: From 3991a1af98baaee193d7c72c6ea55ca0e74e3b54 Mon Sep 17 00:00:00 2001 From: Ching Tong Date: Mon, 19 Sep 2022 22:28:19 -0400 Subject: [PATCH 04/10] Adding a note about the folder that currently exists --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 62ce359..58ab534 100644 --- a/README.md +++ b/README.md @@ -183,6 +183,8 @@ Starting with Person 4 and going backwards, you will now repeat the steps we jus 6. Merge your request. 7. Repeat until all group members have contributed to your repo. + >Note: If you want to see an example of what I did, you can look in the `favorite-animals` folder and the `.py` file with my first and last name. + # And We've finished the Tutorial! Pat yourself on the back, you're well on your way to mastering git. If you have spare time, consider trying to manage a merge conflict, rebasing your pull request instead of merging, or reverting a commit. From 39c9a3faca5fde45eaf549682f655b8c15e3b8b4 Mon Sep 17 00:00:00 2001 From: Kyle Longhurst Date: Mon, 19 Sep 2022 23:11:17 -0600 Subject: [PATCH 05/10] prettier formatting updates --- README.md | 146 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 82 insertions(+), 64 deletions(-) diff --git a/README.md b/README.md index 58ab534..73d3143 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # learn-git-tutorial + A tutorial for those looking to get started using git and github. Originally used on campus at BYU. Git might not get you a job, but it will certainly be an every day tool. It's how world-class dev orgs ship applications. Let's get started! @@ -10,21 +11,23 @@ Git might not get you a job, but it will certainly be an every day tool. It's ho The README of this repo is the tutorial, but you'll use the rest of the files to practice forking, committing, open a PR, etc. This won't teach you everything, but I hope it gives you enough of a base if you get stuck in any sticky situations. ## Pre-requisites: + 1. You have git installed on your machine 2. You have setup your git config with your email and git username. See the section `Your Identity` in [the First Time Git Setup documentation](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) if you haven't done this step. You can make sure that you've done this step by running `git config user.name` and `git config user.email`. ## Step 0: Tutorial Overview + In this tutorial, you will be doing the following steps: + 1. Fork This Repository 2. Clone Your Newly-Created Fork 3. Give edit permissions to your group -3. Create a feature branch on your local repo -4. Add a python script to a new folder -5. Commit your changes -6. Push your local feature branch to your remote repo (your fork) -7. Pull down latest changes from master -8. All team members contribute to newly created repository - +4. Create a feature branch on your local repo +5. Add a python script to a new folder +6. Commit your changes +7. Push your local feature branch to your remote repo (your fork) +8. Pull down latest changes from master +9. All team members contribute to newly created repository ## Step 1: Fork This Repository @@ -38,15 +41,16 @@ After you fork your repo, your newly-created repo will be referred to as a "fork 1. Make sure you're on the base page of the `learn-git` repository: [https://github.comstephengodderidge/learn-git](https://github.com/stephengodderidge/learn-git). 2. In the top right-hand corner, you'll see a button that says "Fork". Click it. - You'll see a screen that shows "Forking repository". You'll now find yourself on a new repo page. If you look in the top left, you'll see that this repo is based on your ``. + You'll see a screen that shows "Forking repository". You'll now find yourself on a new repo page. If you look in the top left, you'll see that this repo is based on your ``. Congrats! You've created a fork! This is simply a copy of the base repository `stephengodderidge/learn-git` ## Step 2: Clone Your Newly-Created Fork + You'll need to clone your fork repository to your local environment. "Clone" might just sound like a fancy way to say "download", but cloning keeps the connection between the remote repository (in GitHub) so you can add our changes (commits) back to the remote. By the end of this step, your will have cloned the repository into a folder on your computer. 1. Go to your fork and hit the green "Code" button. Select HTTPS. -> There are several ways to clone the repository, including SSH and GitHub's own command-line interface. We're going to keep it simple and go with HTTPS. + > There are several ways to clone the repository, including SSH and GitHub's own command-line interface. We're going to keep it simple and go with HTTPS. 2. Copy the link in the box. This link is the url to the repository. It should look something like https://github.com/your-username-here/learn-git.git 3. If you're on a Mac, open your terminal. If you're on windows, use Git BASH. I'm not a PC user, but I'm fairly certain you can download Git BASH on [gitforwindows.org](https://gitforwindows.org/) 4. Navigate to the parent directory you'd like to download it to. @@ -55,6 +59,7 @@ You'll need to clone your fork repository to your local environment. "Clone" mig And Voila! You've officially cloned the repository onto your local machine. Navigate to your repository by running a quick `cd learn-git` ## Step 4: Create a feature branch on your local repo + Now that you're on your local repository, you can focus on making our changes. Your assignment is to create a folder, add code to the same file, make pull requests, pull down latest changes, and manage any merge conflicts. Yes, very complicated. It's basic, but the goal is to learn git. You'll create a folder with a name of your choice with a `.py` file inside. Feel free to name your script whatever you want, commit it to your local repo, push your changes to your fork, and open a repo. Phew, that's a lot! Don't worry, you'll focus on creating the feature branch in this step. 1. Make sure you're in the root of your local repo. Use `cd` to get there. To make sure you're on the master branch, run `git status`. The output will show you your current branch. If you're not on your default branch, run the command in step three to switch back. We'll come back to `git status` in a minute. @@ -70,11 +75,13 @@ Now that you're on your local repository, you can focus on making our changes. Y And voila! You've created your feature branch. You're all set to make these changes. ## Step 5: Add a folder structure and upload to your repository + In this step, you're going to add a script. The important part is that you're going to make changes locally, commit those changes to our feature branch, and ultimately you'll be pushing these changes to our fork. -Before we jump in. Everyone in your group number off from 1-4. We will be splitting up work to make it more collaborative and experience how it feels to contribute to the same repo as your group. +Before we jump in. Everyone in your group number off from 1-4. We will be splitting up work to make it more collaborative and experience how it feels to contribute to the same repo as your group. + +Person 1: -Person 1: 1. Open the `learn-git` folder in your code editor. 2. Add a new folder with a name of your choice. 3. Create a file and name it whatever you may like. Example: i_love_code.py @@ -82,20 +89,22 @@ Person 1: Now you're ready to move on and actually commit your changes! ## Step 6: Commit your changes + Committing your changes adds your changes to the current branch. Before you commit your changes, you have to _stage_ your changes. This step may seem trivial when you're working on a few files (especially in our case), but this step becomes more helpful as you work on more files at once. > Think of an assembly line that creates new cars. The cars are assembled, and they go to a separate location for a quality check before shipping out to the customer. This is what your staged changes are. You work on a bunch of changes locally, and then stage the changes (quality check) before they're finally committed (shipped to the customer). Once you've staged your changes, you can review your changes before finally committing them. Think of committing your staged changes as saving your changes to your repository. Follow the steps below, and we'll come back to this question. -Person 1: +Person 1: + 1. Make sure you saved your new empty `.py` file. 2. Run `git status` to see the files that have been changed. You should see a `Changes not staged for commit:` section. Underneath, you should see the file path to your new script. These are changes that you have saved to your files, but they aren't currently setup to be committed yet. _Your changes aren't staged yet_. In fact, you'll need _add_ them to the staged files before you can commit them. 3. Run `git add {insert_your_folder_name}/{insert_your_script_name}.py`. This step adds the file to the files staged for the commit. - > Note -- if you'd like to stage all of the files you've made changes to locally, you can simply run the shortcut `git add .` instead of adding each file individually. + > Note -- if you'd like to stage all of the files you've made changes to locally, you can simply run the shortcut `git add .` instead of adding each file individually. 4. Run `git status` again to confirm the changes have been added to the staged files. You should see a `Changes to be committed:` section. Underneath, you should see the new file path. This means your files are ready to be committed. @@ -110,25 +119,29 @@ Now, back to the question – _How is saving your files on your computer differe Once you have several commits on a branch, you can choose to do a whole host of different actions - undo (wipe away the changes completely), unstage (un-commit the changes, and add them to the unstaged files on your local workspace), and more. ## Step 7: Push your local feature branch to your remote repo (your fork) + Now that you have your changes committed, you need to _push_ those changes to your remote repository, which is a fork of the original `learn-git` repository. At the end of this step, your remote repository will include your feature branch. 1. Check which branch you're on by running `git status`. If you're not on your feature branch, go ahead and checkout that branch with `git checkout {insert-branch-name}`. - > Note -- If you don't remember the name of your branch, you can run `git branch` in your terminal and it'll display all the branches you have locally. + > Note -- If you don't remember the name of your branch, you can run `git branch` in your terminal and it'll display all the branches you have locally. 2. Run `git push`. Git should automatically display a message similar to: - ``` - The current branch my-animal has no upstream branch. - To push the current branch and set the remote as upstream, use - git push --set-upstream origin my-animal + ``` + The current branch my-animal has no upstream branch. + To push the current branch and set the remote as upstream, use - ``` - Don't worry, nothing is wrong. Git is simply helping us with your next step. Git is telling you that you need to set the upstream branch of your local branch to the remote copy (origin). Phew, that was a lot. Let's break it down. + git push --set-upstream origin my-animal - So, what is `origin`? This is the term that git uses to refer to a remote repo. In our case, origin is our remote repository (our fork). The upstream branch is the branch tracked on the remote repository by your local branch. So, in our case, we're setting up our local branch to track any changes that happen in our origin's (our fork's) branch. When would this be useful? Well, say we have multiple developers making changes to a feature branch. We need a way to pull down the latest commits + ``` + + Don't worry, nothing is wrong. Git is simply helping us with your next step. Git is telling you that you need to set the upstream branch of your local branch to the remote copy (origin). Phew, that was a lot. Let's break it down. + + So, what is `origin`? This is the term that git uses to refer to a remote repo. In our case, origin is our remote repository (our fork). The upstream branch is the branch tracked on the remote repository by your local branch. So, in our case, we're setting up our local branch to track any changes that happen in our origin's (our fork's) branch. When would this be useful? Well, say we have multiple developers making changes to a feature branch. We need a way to pull down the latest commits + + [More on that in this helpful article](https://devconnected.com/how-to-set-upstream-branch-on-git/#:~:text=Upstream%20branches%20define%20the%20branch,set%20upstream%20branches%20on%20Git.) - [More on that in this helpful article](https://devconnected.com/how-to-set-upstream-branch-on-git/#:~:text=Upstream%20branches%20define%20the%20branch,set%20upstream%20branches%20on%20Git.) 3. Do as git suggests and run `git push --set-upstream origin {insert-branch-name}`. You'll see a bunch of update statements like `resolving deltas` and `Writing objects:`. This means git is pushing your local branch to your remote repo. You'll also see a helpful line that should read something similar to this: ``` @@ -142,11 +155,11 @@ Copy this URL. You're going to need it in a minute! ## Step 8: Open a Pull Request - Our next goal is to add our commits to the master branch of our newly created `learn-git` repo so others can see our script and make changes if they'd like. In order to do this, you need to submit a request to pull those changes into the repo. In other words, you need to open a __pull request__. +Our next goal is to add our commits to the master branch of our newly created `learn-git` repo so others can see our script and make changes if they'd like. In order to do this, you need to submit a request to pull those changes into the repo. In other words, you need to open a **pull request**. This Pull Request needs to be approved by the owners of the repository before it can be _merged_ into master. Different companies have different approval processes (example: multiple reviewers from different teams), but our use case is simple. You're simply focused on opening the pull request. -1. Open a request by going to the link in the last step of Step 6. It should look like `https://github.com//learn-git/pull/new/{insert-branch-name}`. This should take you to a page with the title of __Open a pull request__. +1. Open a request by going to the link in the last step of Step 6. It should look like `https://github.com//learn-git/pull/new/{insert-branch-name}`. This should take you to a page with the title of **Open a pull request**. 2. Name your Pull Request whatever you want. Add some comments if you'd like. 3. Once you've added your PR name and comments, go ahead and click the `Create Pull Request`. @@ -154,43 +167,45 @@ Congrats! You've opened your first pull request!! Go ahead and take a look aroun ## Step 9: Approve a Pull Request -Now that the pull request has been created, it needs to be reviewed, approved, and merged into our `master` branch. +Now that the pull request has been created, it needs to be reviewed, approved, and merged into our `master` branch. Since Person 1 has given edit permissions to the whole group and they cannot approve their own pull request. Let's have the person with the nearest birthday in the remaining group (Person 2, 3, or 4) be the approver. 1. Navigate to the Pull Requests tab on GitHub, the url should look something like `https://github.com//learn-git/pulls` 2. Navigate to Files Changed tab -3. Click Review Changes, click `Approve` radio button, and add a comment if you would like, and press submit! +3. Click Review Changes, click `Approve` radio button, and add a comment if you would like, and press submit! - >Note -- It is not good practice to approve a pull request without thoroughly reading over the code and ensuring that what we are putting into master is good code. However, since this tutorial is focused more on git principles rather than coding principles, don't stress too much about mulling over the one line print statement. -4. Once the pull request has been approved, Person 1 can go ahead and merge the pull request. + > Note -- It is not good practice to approve a pull request without thoroughly reading over the code and ensuring that what we are putting into master is good code. However, since this tutorial is focused more on git principles rather than coding principles, don't stress too much about mulling over the one line print statement. +4. Once the pull request has been approved, Person 1 can go ahead and merge the pull request. -Ta daaaa! You have now reviewed a PR, approved the code, and now the code exists in master! We want the whole team to be able to try this whole process that we walked through. +Ta daaaa! You have now reviewed a PR, approved the code, and now the code exists in master! We want the whole team to be able to try this whole process that we walked through. ## Step 10: Rinse and Repeat -Starting with Person 4 and going backwards, you will now repeat the steps we just walked through. This is your time to collaborate together and try to remember what we have learned so far. +Starting with Person 4 and going backwards, you will now repeat the steps we just walked through. This is your time to collaborate together and try to remember what we have learned so far. + 1. Pull down the latest code in master -2. Add a print statement to your `.py` file. This can be anything you want. You can share your favorite joke, animal, etc. An example could be: +2. Add a print statement to your `.py` file. This can be anything you want. You can share your favorite joke, animal, etc. An example could be: + + ```python + print("My favorite animal is a dolphin") + ``` - ```python - print("My favorite animal is a dolphin") - ``` 3. Save your file and make a commit containing your changes 4. Create a pull request 5. Ask a group member to approve your pull request -6. Merge your request. -7. Repeat until all group members have contributed to your repo. - - >Note: If you want to see an example of what I did, you can look in the `favorite-animals` folder and the `.py` file with my first and last name. +6. Merge your request. +7. Repeat until all group members have contributed to your repo. + > Note: If you want to see an example of what I did, you can look in the `favorite-animals` folder and the `.py` file with my first and last name. -# And We've finished the Tutorial! Pat yourself on the back, you're well on your way to mastering git. If you have spare time, consider trying to manage a merge conflict, rebasing your pull request instead of merging, or reverting a commit. +# And We've finished the Tutorial! Pat yourself on the back, you're well on your way to mastering git. If you have spare time, consider trying to manage a merge conflict, rebasing your pull request instead of merging, or reverting a commit. ## More Content: ### Commands that were used in this tutorial: + ``` git clone git remote -v @@ -206,54 +221,57 @@ git push git push --set-upstream origin ``` -> note: DON'T Simply run these commands in order. There is some overlap. This list is mainly meant to be a reference for later. Remembering all of the git commands can be tricky. __I still regularly google Git commands__, and I've used Git every day for the last 3 years or so. - +> note: DON'T Simply run these commands in order. There is some overlap. This list is mainly meant to be a reference for later. Remembering all of the git commands can be tricky. **I still regularly google Git commands**, and I've used Git every day for the last 3 years or so. ### Other Great Tutorials: + Need more practice? Take a look at some of these tutorials to expand your experience (Don't worry, they're free!): -* [Kent C Dodd's Intro to GitHub](https://egghead.io/lessons/javascript-introduction-to-github) -- an Awesome course that helped me fill in some gaps of my knowledge about GitHub way back when. -* [Kent C Dodd's Intro to Contributing to Open Source](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) -- the best way to learn is to do, and this is a great course for contributing to real projects on github. -* Another good [step-by-step guide from opensource.com](https://opensource.com/article/18/1/step-step-guide-git) -* Here's [an interactive git playground](https://learngitbranching.js.org/?NODEMO) that you can practice branching +- [Kent C Dodd's Intro to GitHub](https://egghead.io/lessons/javascript-introduction-to-github) -- an Awesome course that helped me fill in some gaps of my knowledge about GitHub way back when. +- [Kent C Dodd's Intro to Contributing to Open Source](https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github) -- the best way to learn is to do, and this is a great course for contributing to real projects on github. +- Another good [step-by-step guide from opensource.com](https://opensource.com/article/18/1/step-step-guide-git) +- Here's [an interactive git playground](https://learngitbranching.js.org/?NODEMO) that you can practice branching ### Topics Not Covered + This tutorial doesn't cover these topics, but they're still useful to know after you've learned everything included above: -* __How to undo your last commit__ - See the second answer to [this post on Stackoverflow](https://stackoverflow.com/questions/927358/how-do-i-undo-the-most-recent-local-commits-in-git). +- **How to undo your last commit** - See the second answer to [this post on Stackoverflow](https://stackoverflow.com/questions/927358/how-do-i-undo-the-most-recent-local-commits-in-git). -* __How to view your current changes in VSCode__ - I definitely recommend using VSCode if you can. I run all of my git commands and logic through the command line, but I use the git tab on the far right toolbar to view the changes to my files. See `[the VS Code documentation for more info](https://code.visualstudio.com/docs/editor/versioncontrol). +- **How to view your current changes in VSCode** - I definitely recommend using VSCode if you can. I run all of my git commands and logic through the command line, but I use the git tab on the far right toolbar to view the changes to my files. See `[the VS Code documentation for more info](https://code.visualstudio.com/docs/editor/versioncontrol). -* __How to _Rebase_ Your Feature Branch Onto the latest version of Master__ - Let's say you're working on your feature branch for a few days, and the upstream master has been updated, and you need the new changes on your feature branch. The process to do this is called "rebasing". It's a good one to know. I'll work on adding a tutorial for it, but in the meantime, you can always Google "how to rebase my branch onto master" and a Stack Overflow link should pop up. +- **How to _Rebase_ Your Feature Branch Onto the latest version of Master** - Let's say you're working on your feature branch for a few days, and the upstream master has been updated, and you need the new changes on your feature branch. The process to do this is called "rebasing". It's a good one to know. I'll work on adding a tutorial for it, but in the meantime, you can always Google "how to rebase my branch onto master" and a Stack Overflow link should pop up. -* __How to Resolve Merge Conflicts__ - Let's say you open a PR that changes files that someone else changed _after you created your branch_. Your branch doesn't have these changes, so Git isn't sure how it should treat the order of the commits. This is called a Merge Conflict. - This is the trickiest part of working in git. This will most certainly cause you headaches in the future. It's worth an entire tutorial by itself. I'm working on adding a full-fledge tutorial, but here are the basic steps: (A) Pull the latest changes from the upstream master into the local master. (B) Checkout the feature branch that has the conflicts. (C) Rebase your feature branch onto master. (D) Use the interactive rebasing process to resolve any conflicts. (E) Force push your changes. Again, I'll add a full-fledge tutorial soon, but hopefully these steps give you a guide for things to Google. +- **How to Resolve Merge Conflicts** - Let's say you open a PR that changes files that someone else changed _after you created your branch_. Your branch doesn't have these changes, so Git isn't sure how it should treat the order of the commits. This is called a Merge Conflict. + This is the trickiest part of working in git. This will most certainly cause you headaches in the future. It's worth an entire tutorial by itself. I'm working on adding a full-fledge tutorial, but here are the basic steps: (A) Pull the latest changes from the upstream master into the local master. (B) Checkout the feature branch that has the conflicts. (C) Rebase your feature branch onto master. (D) Use the interactive rebasing process to resolve any conflicts. (E) Force push your changes. Again, I'll add a full-fledge tutorial soon, but hopefully these steps give you a guide for things to Google. ### Terms to be familiar with: + Here are some of the terms we've used in the tutorial. This isn't meant to be a comprehensive git dictionary, but hopefully it helps fill in any gaps you might have after the tutorial. -* __repository__ - the git-enabled folder. Think of it as your project folder with a hidden .git folder inside. This repository can have branches, forks, and various commits. The main goal is that it tracks all of the versions of a project, both working and development. AKA "a repo." +- **repository** - the git-enabled folder. Think of it as your project folder with a hidden .git folder inside. This repository can have branches, forks, and various commits. The main goal is that it tracks all of the versions of a project, both working and development. AKA "a repo." + +- **branch** - think of branches as pointers to a snapshot of your changes. The default branch in git is referred to as `master` or `main`. Branches are used for new feature development. The process to switch to a new branch is called "check out a branch." Each time you create a branch, you create a new snapshot of the branch you currently had checked out. -* __branch__ - think of branches as pointers to a snapshot of your changes. The default branch in git is referred to as `master` or `main`. Branches are used for new feature development. The process to switch to a new branch is called "check out a branch." Each time you create a branch, you create a new snapshot of the branch you currently had checked out. +- **commit** - -* __commit__ - - * _verb_: to write your changes to whichever branch you're currently on. - * _noun_: refers to the new changes themselves. Once you've committed your changes, you can undo those changes by undoing the commit. Git uses hashes to refer to your various commits. + - _verb_: to write your changes to whichever branch you're currently on. + - _noun_: refers to the new changes themselves. Once you've committed your changes, you can undo those changes by undoing the commit. Git uses hashes to refer to your various commits. -* __remote__ - opposite of local. Used to describe a repo that exists in GitHub (or a different git service). By default, your local repo will have one remote: `origin`. You can add other remotes as well. This is helpful when you want to pull the latest changes from the original repository that your fork is generated from (see Step 2.5 above in the tutorial). +- **remote** - opposite of local. Used to describe a repo that exists in GitHub (or a different git service). By default, your local repo will have one remote: `origin`. You can add other remotes as well. This is helpful when you want to pull the latest changes from the original repository that your fork is generated from (see Step 2.5 above in the tutorial). -* __local__ - opposite of remote. Used to describe a repo that exists on your local machine. +- **local** - opposite of remote. Used to describe a repo that exists on your local machine. -* __fork__ - a copy of someone else's repository. This new copy is owned by your GitHub user, so you're able to make changes to it. This is a very common approach in the open-source contributing world. See Step 1. +- **fork** - a copy of someone else's repository. This new copy is owned by your GitHub user, so you're able to make changes to it. This is a very common approach in the open-source contributing world. See Step 1. -* __pull request__ - a request to merge your changes into a branch (usually master). Think of it as a request to _pull your feature branch's changes into the master branch_. Note that these feature branches can be on a fork of the original/upstream/main repo. +- **pull request** - a request to merge your changes into a branch (usually master). Think of it as a request to _pull your feature branch's changes into the master branch_. Note that these feature branches can be on a fork of the original/upstream/main repo. -* __push__ - Used to describe the process of adding your commit to another branch, usually from a local to a remote. Example: _Push your changes (commit) to your remote repo_. +- **push** - Used to describe the process of adding your commit to another branch, usually from a local to a remote. Example: _Push your changes (commit) to your remote repo_. -* __pull__ - Used to describe the process of adding the changes from one branch to another, usually from a remote to a local. _Pull in the latest changes from the master branch_. +- **pull** - Used to describe the process of adding the changes from one branch to another, usually from a remote to a local. _Pull in the latest changes from the master branch_. -*__master__ - Used as the default branch for any repository. There is nothing special about this branch; it's simply the one that is designated as the main branch +- **master** - Used as the default branch for any repository. There is nothing special about this branch; it's simply the one that is designated as the main branch - > Because of today's society's realization of systemic racism, there are movements to rename "master" to "main." I think this is an important and necessary shift in our verbiage as developers. GitHub will soon make it the default for all repositories. However, in the meantime, for those learning git, it is still helpful to learn "master" as the default branch. New developers will most certainly come across repos with a `Master` branch and need to be aware of what that means. For this reason, I'm going to continue to use `master/main` to refer to the default branch. + > Because of today's society's realization of systemic racism, there are movements to rename "master" to "main." I think this is an important and necessary shift in our verbiage as developers. GitHub will soon make it the default for all repositories. However, in the meantime, for those learning git, it is still helpful to learn "master" as the default branch. New developers will most certainly come across repos with a `Master` branch and need to be aware of what that means. For this reason, I'm going to continue to use `master/main` to refer to the default branch. -__Did I miss a term? Go ahead and open a PR to add any you think should be added!__ +**Did I miss a term? Go ahead and open a PR to add any you think should be added!** From 988f2bf9efbba3992be7d45fe85290ce27ece248 Mon Sep 17 00:00:00 2001 From: Kyle Longhurst Date: Tue, 20 Sep 2022 11:29:38 -0600 Subject: [PATCH 06/10] Update intro, pre-reqs, and step 1 & 2 --- README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 75 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 73d3143..c9549f1 100644 --- a/README.md +++ b/README.md @@ -14,14 +14,38 @@ The README of this repo is the tutorial, but you'll use the rest of the files to 1. You have git installed on your machine 2. You have setup your git config with your email and git username. See the section `Your Identity` in [the First Time Git Setup documentation](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup) if you haven't done this step. You can make sure that you've done this step by running `git config user.name` and `git config user.email`. +3. You have [created an account on Github](https://github.com/signup). -## Step 0: Tutorial Overview +## Tutorial Overview -In this tutorial, you will be doing the following steps: +> Git is a [distributed version control system](https://en.wikipedia.org/wiki/Distributed_version_control). Let's break down what that means... + +### Version Control System + +You are probably familiar with a "version control system," although, you might not call it that. Have you ever edited a Word document can called it something like `My Document_final_FINAL.docx`? Voila! Little did you know, but you were using your very own version control system. + +But if you have named your files in this way, you know it is difficult to keep track of all the files and the various changes you made across files. + +This is where git shines! When you use git you will only have one file version on your computer at a time and git will track all of the file versions and history for you behind the scenes! Then you can compare versions or switch back to an old version whenever you need. + +### Distributed Version Control System + +Git is a **_Distributed_** version control system because it not only allows you to track versions of files on your computer but across your devices, team members computers, and servers. Git enables easy remote backup and collaboration with your team! No more emailing `.zip` files or passing around [punch cards](https://en.wikipedia.org/wiki/Computer_programming_in_the_punched_card_era). 🚀 + +### Tutorial Steps + +This tutorial is designed as a team assignment where you can learn to use Git as a powerful collaboration tool. The tutorial will be divided into two parts. In the first part, one team member will do the initial setup of a shared project where all the team members can contribute. The second part will consist of every team member making code changes on their machine and then combining the code into the shared project. + +Here is the tutorial breakdown: + +#### Part 1 (One Team Member) 1. Fork This Repository 2. Clone Your Newly-Created Fork -3. Give edit permissions to your group +3. Give edit permissions to your team + +#### Part 2 (All Team Members) + 4. Create a feature branch on your local repo 5. Add a python script to a new folder 6. Commit your changes @@ -29,23 +53,59 @@ In this tutorial, you will be doing the following steps: 8. Pull down latest changes from master 9. All team members contribute to newly created repository -## Step 1: Fork This Repository +## Part 1 - Setup Team Repository + +Alright! Pick one team member that will do the initial project setup and then let's git to it! 😉 + +### Step 1: Fork This Repository > Repository (Repo): A folder that holds your code. This folder is special because it has a hidden `.git` folder that holds information about how your repository has changed over time. Instead of adding your changes directly to someone else's repo, you can create a copy of their repository to work with. When you create this copy, we call it "forking the repository." -Conceptually, think about hitting a fork in the road -- the road splits into two. This is the same with forking in git. Forking simply creates a snapshot of the base repository (`stephengodderidge/learn-git`) that you have permission to make changes to. +Conceptually, think about hitting a fork in the road -- the road splits into two. This is the same with forking in git. Forking simply creates a snapshot of the base repository (`chingtong/learn-git`) that you have permission to make changes to. After you fork your repo, your newly-created repo will be referred to as a "fork." This might sound weird, but just go with it. I promise it will stick eventually. -1. Make sure you're on the base page of the `learn-git` repository: [https://github.comstephengodderidge/learn-git](https://github.com/stephengodderidge/learn-git). +1. Make sure you're on the base page of the `learn-git` repository: [https://github.com/chingtong/learn-git](https://github.com/chingtong/learn-git). 2. In the top right-hand corner, you'll see a button that says "Fork". Click it. You'll see a screen that shows "Forking repository". You'll now find yourself on a new repo page. If you look in the top left, you'll see that this repo is based on your ``. -Congrats! You've created a fork! This is simply a copy of the base repository `stephengodderidge/learn-git` +Congrats! You've created a fork! This is simply a copy of the base repository `chingtong/learn-git`. We will use this new repository as a place for your team can share code. + +### Step 2: Give edit permissions to your team + +Your team members need edit permissions to the team repository so they can save their code there without requiring your approval. + +Add a new repository collaborators by going to `Settings > Collaborators` then clicking `Add people`. You will need your team members' github usernames or email addresses. + +> **Bonus step: Prevent unwanted changes to `master` branch** +> +> > _If any of the terms here are confusing, don't worry! You can skip this step and come back to enable branch protection at any time_ +> +> We want to protect our code against unwanted or accidental changes. For example, it is possbile to accidently delete the version history of our repository. Yikes! +> +> Navigate to `Settings > Branches`, then in the `Branch protection rule` section click `add rule`. In the "Branch name pattern" box type `master`. +> Then enable the following settings: +> +> 1. Require a pull request before merging +> 2. Require approvals +> 3. Dismiss stale pull request approvals when new commits are pushed +> 4. Do not allow bypassing the above settings +> +> Then click `Create` +> +> This step will protect your `master` branch from unwanted changes. Based on the settings above, changes to `master` will require that another team member review your code before it can be saved via a `pull request` + +> Open Source vs Team Repository + +#### (Do we want to add branch protection to master?) + +## Part 2 - Team Collaboration (feat. Git) + +Okay now that everyone has access to the team repository, it is time for everyone to put their hands to the keyboard. Let's code! -## Step 2: Clone Your Newly-Created Fork +### Step 3: Clone Your Newly-Created Fork You'll need to clone your fork repository to your local environment. "Clone" might just sound like a fancy way to say "download", but cloning keeps the connection between the remote repository (in GitHub) so you can add our changes (commits) back to the remote. By the end of this step, your will have cloned the repository into a folder on your computer. @@ -58,7 +118,7 @@ You'll need to clone your fork repository to your local environment. "Clone" mig And Voila! You've officially cloned the repository onto your local machine. Navigate to your repository by running a quick `cd learn-git` -## Step 4: Create a feature branch on your local repo +### Step 4: Create a feature branch on your local repo Now that you're on your local repository, you can focus on making our changes. Your assignment is to create a folder, add code to the same file, make pull requests, pull down latest changes, and manage any merge conflicts. Yes, very complicated. It's basic, but the goal is to learn git. You'll create a folder with a name of your choice with a `.py` file inside. Feel free to name your script whatever you want, commit it to your local repo, push your changes to your fork, and open a repo. Phew, that's a lot! Don't worry, you'll focus on creating the feature branch in this step. @@ -74,7 +134,7 @@ Now that you're on your local repository, you can focus on making our changes. Y And voila! You've created your feature branch. You're all set to make these changes. -## Step 5: Add a folder structure and upload to your repository +### Step 5: Add a folder structure and upload to your repository In this step, you're going to add a script. The important part is that you're going to make changes locally, commit those changes to our feature branch, and ultimately you'll be pushing these changes to our fork. @@ -88,7 +148,7 @@ Person 1: Now you're ready to move on and actually commit your changes! -## Step 6: Commit your changes +### Step 6: Commit your changes Committing your changes adds your changes to the current branch. Before you commit your changes, you have to _stage_ your changes. This step may seem trivial when you're working on a few files (especially in our case), but this step becomes more helpful as you work on more files at once. @@ -118,7 +178,7 @@ Now, back to the question – _How is saving your files on your computer differe Once you have several commits on a branch, you can choose to do a whole host of different actions - undo (wipe away the changes completely), unstage (un-commit the changes, and add them to the unstaged files on your local workspace), and more. -## Step 7: Push your local feature branch to your remote repo (your fork) +### Step 7: Push your local feature branch to your remote repo (your fork) Now that you have your changes committed, you need to _push_ those changes to your remote repository, which is a fork of the original `learn-git` repository. At the end of this step, your remote repository will include your feature branch. @@ -153,7 +213,7 @@ Copy this URL. You're going to need it in a minute! 4. Bonus -- go to your fork in your browser. In the top left corner, you should see a button that says `Master`. Click it, and see that your branch is there. You can open you branch and navigate to your script. You should be able to see your changes. Pretty cool right? -## Step 8: Open a Pull Request +### Step 8: Open a Pull Request Our next goal is to add our commits to the master branch of our newly created `learn-git` repo so others can see our script and make changes if they'd like. In order to do this, you need to submit a request to pull those changes into the repo. In other words, you need to open a **pull request**. @@ -165,7 +225,7 @@ This Pull Request needs to be approved by the owners of the repository before it Congrats! You've opened your first pull request!! Go ahead and take a look around at the different tabs. See if you can find where you can view your changes (Hint: look for files). You can also view your commit(s). -## Step 9: Approve a Pull Request +### Step 9: Approve a Pull Request Now that the pull request has been created, it needs to be reviewed, approved, and merged into our `master` branch. @@ -181,7 +241,7 @@ Since Person 1 has given edit permissions to the whole group and they cannot app Ta daaaa! You have now reviewed a PR, approved the code, and now the code exists in master! We want the whole team to be able to try this whole process that we walked through. -## Step 10: Rinse and Repeat +### Step 10: Rinse and Repeat Starting with Person 4 and going backwards, you will now repeat the steps we just walked through. This is your time to collaborate together and try to remember what we have learned so far. From 17decbb4946086a008e6079f6e7c0ca6d0c973be Mon Sep 17 00:00:00 2001 From: Kyle Longhurst Date: Tue, 20 Sep 2022 11:34:52 -0600 Subject: [PATCH 07/10] Updated step numbering and some wording in step 3 --- README.md | 38 ++++++++++++++++++-------------------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index c9549f1..eb9ff1a 100644 --- a/README.md +++ b/README.md @@ -41,17 +41,16 @@ Here is the tutorial breakdown: #### Part 1 (One Team Member) 1. Fork This Repository -2. Clone Your Newly-Created Fork -3. Give edit permissions to your team +2. Give edit permissions to your team #### Part 2 (All Team Members) -4. Create a feature branch on your local repo -5. Add a python script to a new folder -6. Commit your changes -7. Push your local feature branch to your remote repo (your fork) -8. Pull down latest changes from master -9. All team members contribute to newly created repository +3. Create a feature branch on your local repo +4. Add a python script to a new folder +5. Commit your changes +6. Push your local feature branch to your remote repo (your fork) +7. Pull down latest changes from master +8. All team members contribute to newly created repository ## Part 1 - Setup Team Repository @@ -68,16 +67,19 @@ Conceptually, think about hitting a fork in the road -- the road splits into two After you fork your repo, your newly-created repo will be referred to as a "fork." This might sound weird, but just go with it. I promise it will stick eventually. 1. Make sure you're on the base page of the `learn-git` repository: [https://github.com/chingtong/learn-git](https://github.com/chingtong/learn-git). -2. In the top right-hand corner, you'll see a button that says "Fork". Click it. - You'll see a screen that shows "Forking repository". You'll now find yourself on a new repo page. If you look in the top left, you'll see that this repo is based on your ``. +2. In the top right-hand corner, you'll see a button that says `Fork`. Click it. You'll see a screen that shows "Forking repository". You'll now find yourself on a new repo page. If you look in the top left, you'll see that this repo is based on your ``. Congrats! You've created a fork! This is simply a copy of the base repository `chingtong/learn-git`. We will use this new repository as a place for your team can share code. +> Now is a good time to copy the url for your new repository (e.g. `https://github.com/`) and share it with your team. They will use it in Step 3 + ### Step 2: Give edit permissions to your team +> You will need your team members' github usernames or email addresses for this step. + Your team members need edit permissions to the team repository so they can save their code there without requiring your approval. -Add a new repository collaborators by going to `Settings > Collaborators` then clicking `Add people`. You will need your team members' github usernames or email addresses. +Add a new repository collaborators by going to `Settings > Collaborators` then clicking `Add people`. > **Bonus step: Prevent unwanted changes to `master` branch** > @@ -97,26 +99,22 @@ Add a new repository collaborators by going to `Settings > Collaborators` then c > > This step will protect your `master` branch from unwanted changes. Based on the settings above, changes to `master` will require that another team member review your code before it can be saved via a `pull request` -> Open Source vs Team Repository - -#### (Do we want to add branch protection to master?) - ## Part 2 - Team Collaboration (feat. Git) -Okay now that everyone has access to the team repository, it is time for everyone to put their hands to the keyboard. Let's code! +Okay now that everyone has access to the team repository, it is time for everyone to put their hands to the keyboard so we can practice collaborating with Git. Let's code! -### Step 3: Clone Your Newly-Created Fork +### Step 3: Clone Your Newly-Created Team Fork -You'll need to clone your fork repository to your local environment. "Clone" might just sound like a fancy way to say "download", but cloning keeps the connection between the remote repository (in GitHub) so you can add our changes (commits) back to the remote. By the end of this step, your will have cloned the repository into a folder on your computer. +You'll need to clone your team's forked repository to your local environment. "Clone" might just sound like a fancy way to say "download", but cloning keeps the connection between the remote repository (in GitHub) so you can add our changes (commits) back to the remote. By the end of this step, your will have cloned the repository into a folder on your computer. -1. Go to your fork and hit the green "Code" button. Select HTTPS. +1. Go to your team's fork and hit the green "Code" button. Select HTTPS. > There are several ways to clone the repository, including SSH and GitHub's own command-line interface. We're going to keep it simple and go with HTTPS. 2. Copy the link in the box. This link is the url to the repository. It should look something like https://github.com/your-username-here/learn-git.git 3. If you're on a Mac, open your terminal. If you're on windows, use Git BASH. I'm not a PC user, but I'm fairly certain you can download Git BASH on [gitforwindows.org](https://gitforwindows.org/) 4. Navigate to the parent directory you'd like to download it to. 5. Type the following command: `git clone ` -And Voila! You've officially cloned the repository onto your local machine. Navigate to your repository by running a quick `cd learn-git` +And Ta-da! You've officially cloned the repository onto your local machine. Navigate to your repository by running a quick `cd learn-git` ### Step 4: Create a feature branch on your local repo From 6e8650551cd9c611c8fad1080e9c8f1bb6377e16 Mon Sep 17 00:00:00 2001 From: Kyle Longhurst Date: Tue, 20 Sep 2022 11:45:36 -0600 Subject: [PATCH 08/10] fix typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index eb9ff1a..e5a53b1 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ The README of this repo is the tutorial, but you'll use the rest of the files to ### Version Control System -You are probably familiar with a "version control system," although, you might not call it that. Have you ever edited a Word document can called it something like `My Document_final_FINAL.docx`? Voila! Little did you know, but you were using your very own version control system. +You are probably familiar with a "version control system," although, you might not call it that. Have you ever edited a Word document and called it something like `My Document_final_FINAL.docx`? Voila! Little did you know, but you were using your very own version control system. But if you have named your files in this way, you know it is difficult to keep track of all the files and the various changes you made across files. From 469d224d6a1825bd5a6b891dca051857b49ef165 Mon Sep 17 00:00:00 2001 From: Kyle Longhurst Date: Tue, 20 Sep 2022 11:47:30 -0600 Subject: [PATCH 09/10] small formatting changes --- README.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index e5a53b1..de826f7 100644 --- a/README.md +++ b/README.md @@ -24,13 +24,11 @@ The README of this repo is the tutorial, but you'll use the rest of the files to You are probably familiar with a "version control system," although, you might not call it that. Have you ever edited a Word document and called it something like `My Document_final_FINAL.docx`? Voila! Little did you know, but you were using your very own version control system. -But if you have named your files in this way, you know it is difficult to keep track of all the files and the various changes you made across files. - -This is where git shines! When you use git you will only have one file version on your computer at a time and git will track all of the file versions and history for you behind the scenes! Then you can compare versions or switch back to an old version whenever you need. +But if you have named your files in this way, you know it is difficult to keep track of all the files and the various changes you made across files. This is where Git shines! When you use Git you will only have one file version on your computer at a time and Git will track all of the file versions and history for you behind the scenes! Then you can compare versions or switch back to an old version whenever you need. ### Distributed Version Control System -Git is a **_Distributed_** version control system because it not only allows you to track versions of files on your computer but across your devices, team members computers, and servers. Git enables easy remote backup and collaboration with your team! No more emailing `.zip` files or passing around [punch cards](https://en.wikipedia.org/wiki/Computer_programming_in_the_punched_card_era). 🚀 +Git is a **_Distributed_** version control system because it not only allows you to track versions of files on your computer but across your devices, team members' computers, and servers. Git enables easy remote backup and collaboration with your team! No more emailing `.zip` files or passing around [punch cards](https://en.wikipedia.org/wiki/Computer_programming_in_the_punched_card_era). 🚀 ### Tutorial Steps From 306f3c931fbf01c7782ecb5fecc2cc7688c63c64 Mon Sep 17 00:00:00 2001 From: Kyle Longhurst Date: Tue, 20 Sep 2022 11:53:33 -0600 Subject: [PATCH 10/10] Wording update to add new team members --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index de826f7..69e3012 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ Congrats! You've created a fork! This is simply a copy of the base repository `c Your team members need edit permissions to the team repository so they can save their code there without requiring your approval. -Add a new repository collaborators by going to `Settings > Collaborators` then clicking `Add people`. +Add new repository collaborators by going to `Settings > Collaborators` then clicking `Add people`. Add all of the members of your team. They should all receive a github notification where they can accept your invitation to collaborate on the repo. > **Bonus step: Prevent unwanted changes to `master` branch** >