Merge pull request #264 from emiliom/git-prep-fixes

Fixes and improvements to Git Preparation page

Author: emiliom

resources/prep/git.md

@@ -4,15 +4,15 @@
 
 [Git](https://git-scm.com/) is a popular version control system that is the foundation of most open source software development. You are not required to be a Git pro in advance of this event, but come prepared to learn a lot about it! [GitHub](https://github.com) is a hosting service for Git repositories, enabling us to share code across teams in a web environment.
 
-We will use Git and GitHub for collaborative work. Be sure to arrive at OceanHackWeek with your own [GitHub](https://github.com/) account.
+We will use Git and GitHub for collaborative work. Be sure to arrive at OceanHackWeek with your own [GitHub](https://github.com) account.
 
 ## Git Installation
 
 * Windows
     * Install Git for Windows from this [link](https://gitforwindows.org/). For more setup details follow these [instructions](https://carpentries.github.io/workshop-template/#shell)
 * Mac OS
     * Download the [git installer](https://git-scm.com/download/mac) and run it. 
-* Linux (Debian): `sudo apt install git-all`
+* Linux (Debian/Ubuntu): `sudo apt install git-all`
 
 To test, open the terminal (on Windows, Git Bash) and setup your username and email:
 
@@ -29,7 +29,7 @@ During the hackweek it will be useful to know how to navigate between files from
 
 ## Terminal (command line) text editor
 
-When working on the command line (the terminal or shell), it is often handy to modify file content directly from there. For that you can use a command line editor such as [nano](https://linuxize.com/post/how-to-use-nano-text-editor/). On Mac and Linux it is usually pre-installed, but for Windows you can follow the instructions in this [link](http://carpentries.github.io/workshop-template/#editor) to set it up. Test your installation by opening a terminal and running `nano --version`. If it works you can link your git configuration with `nano`:
+When working on the command line (the terminal or shell), it is often handy to modify file content directly from there. For that you can use a command line editor such as [nano](https://linuxize.com/post/how-to-use-nano-text-editor/). On Mac and Linux it is usually pre-installed, and on Windows it is installed when you install Git (see [here](http://carpentries.github.io/workshop-template/#editor) for more information about nano and its configuration). Test your installation by opening a terminal and running `nano --version`. If it works you can link your git configuration with `nano`:
 
 ```bash
 git config --global core.editor "nano -w"
@@ -42,10 +42,9 @@ git config --global core.editor "nano -w"
 Steps 1-5 focus on the Git "centralized workflow". We present it here as an illustration, but **the workflow we recommend for use in OceanHackWeek is the Git Fork - Clone workflow, discussed in Step 6.**
 ```
 
-
 ### 1. Create a project repository
 
-On your own or someone in your project group (preferably one who has never done it before), create a repository for the project under the {OceanHackWeek organization, [https://github.com/oceanhackweek](https://github.com/oceanhackweek)
+On your own or someone in your project group (preferably one who has never done it before), create a repository for the project under the `oceanhackweek` organization, `https://github.com/oceanhackweek`
 
 ![New Repo](../img/newRepo.png)
 
@@ -58,13 +57,13 @@ Click `New` and follow the steps: check yes to create a `README.md` file.
 
 ### 2. Clone the repository
 
-Each participant should clone the repository so they have their copy on their JupyterHub account space (and locally in the participant's computer, if desired). Navigate through the terminal to the folder where you want to keep {OceanHackWeek work (`cd path_to_oceanhackweek`).
+Each participant should clone the repository so they have their copy on their JupyterHub account space (and locally in the participant's computer, if desired). Navigate through the terminal to the folder where you want to keep OceanHackWeek work (`cd path_to_oceanhackweek`).
 
 ```bash
 git clone https://github.com/oceanhackweek/ohw22-proj-myprojectname.git
 ```
 
-This will create a new folder called `ohw22-proj-myprojectname`. Navigate to the new folder, `ohw22-proj-myprojectname`.
+This will create a new folder called `ohw22-proj-myprojectname`. Navigate (`cd`) to this new folder.
 
 ### 3. Update the README with your name
 
@@ -82,11 +81,10 @@ Make sure your change appears online.
 `git status` to observe the changes made into your repository. Pay attention to the colors. To see the changes in the files run `git diff`.
 ```
 
-
 ### 4. Update your local repository (local clone) with the changes of your collaborators
 
 ```bash
-git pull origin master
+git pull origin main
 ```
 
 ```{admonition} "Short names for repositories:"
@@ -98,21 +96,23 @@ To continue practicing these steps, make more changes to the title and the descr
 
 ![Centralized Workflow](../img/centralized_workflow.png)
 
-*Ran into a problem?*
 
-When working with several people sometimes you
+```{admonition} *Ran into a problem?*
+:class: attention
 
-* cannot push because changes have been made that have not been incorporated: need to first pull
-* when pulling you arrive into a merge conflict: need to resolve the conflict manually
+When working with several people sometimes you
 
+* Cannot push because changes have been made that have not been incorporated: need to first pull
+* When pulling you arrive into a merge conflict: need to resolve the conflict manually
+```
 
 ### 5. Resolving the merge conflict
 
 ```bash
 git status
 ```
 
-You will see the file/s which caused the merge conflict in green.
+You will see the file(s) which caused the merge conflict in green.
 
 Open it and detect the conflict by the special format:
 
@@ -129,7 +129,7 @@ Decide which changes you want to keep, and modify the file so it looks as you wi
 ```bash
 git add README.md
 git commit -m "resolving merge conflict"
-git push origin master
+git push origin main
 ```
 
 You can continue working on as usual.
@@ -138,7 +138,6 @@ You can continue working on as usual.
 ... to avoid messing with complicated merges and keep your repo up-to-date.
 ```
 
-
 ### 6. Avoiding problems: forking workflow
 
 So far you collaborated using what is called a "centralized git workflow": i.e. every collaborator makes directly changes to the repo.
@@ -160,18 +159,18 @@ Forks are public copies of the main repo, from which you can submit changes to t
 * Fork the public repo (click on the *Fork* button)
 ![](../img/fork_button.png)
 * Note it looks the same but the web address contains your username
-  [https://github.com/myghusername/ohw21-proj-ProjectName](https://github.com/myghusername/ohw21-proj-ProjectName)
+  `https://github.com/myghusername/ohw22-proj-myprojectname`
 * Go to your local repo and rename your `origin` to point to the fork:
 
 ```bash
 git remote rm origin
-git remote add origin https://github.com/myghusername/ohw21-proj-ProjectName.git
+git remote add origin https://github.com/myghusername/ohw22-proj-myprojectname.git
 ```
 
 * Add a new remote to talk to the main repo:
 
 ```bash
-git remote add upstream https://github.com/oceanhackweek/ohw21-proj-ProjectName.git 
+git remote add upstream https://github.com/oceanhackweek/ohw22-proj-myprojectname.git 
 ```
 
 From now on you will push to `origin`, but pull from `upstream`.
@@ -192,7 +191,7 @@ Make some changes to a file and commit and publish them.
 ```bash
 git add README.md
 git commit -m "more changes"
-git push origin master
+git push origin main
 ```
 
 ```{admonition} Note
@@ -240,6 +239,7 @@ git revert HEAD
 Your files in the local repo will still be there.
 ```
 
+
 ## References and Resources
 
 Git and GitHub are very powerful tools but no doubt the learning curve is steep. Learning is an iterative process so below we list some resources which can help you be better prepared: