koudyk / intro_git_github

Introduction to git and GitHub

Introduction to git and GitHub

Hello! 👋 I'm Kendra Oudyk

Git and GitHub are key tools for doing version control in both academia and industry. These tools can help researchers do more efficient, open, and reproducible work. In this material, we cover these topics:

• What is distributed version control?
• Why has it become so important in science and industry?;
• How to track your own work using Git; and
• How to share your work and collaborate with GitHub.

Pre-recorded lecture

Here is my pre-recorded lecture (slides) that goes over the topics listed above.

Before the in-class tutorial

For this tutorial, you'll need

1. To have watched the pre-recorded lecture
2. A Bash shell
3. The version control system Git
4. A text editor you’re comfortable with
5. A GitHub account.
6. A modern browser

Before class, please follow the installation instructions to make sure you have all these requirements.

Acknowledgements

Many parts of these material are inspired / based on these great resources:

Chacon, S., & Straub, B. (2014). Pro git. Springer Nature. Available at https://git-scm.com/book/en/v2

The Carpentries. (2021). Version Control with Git. https://swcarpentry.github.io/git-novice/

intro_git_github's Issues

Task 2a: Address an issue in a collaborative project

GOAL: practice the workflow of contributing to an open project, in particular, addressing an issue posted by someone else
TASK: add a file called <your_username>.csv in the folder ssc_workshop, containing a comma-separated list of your favorite desserts.
NOTE: replace things inside <> with your own info

0. Comment on this issue saying that you can work on it

1. Fork this repository ("Fork" button on top right of this page)

2. Clone your fork to your machine
   git clone https://github.com/<your_username>/intro_git_github.git
   If that doesn't work, try
   git clone [email protected]:<github username>/<github repo name>.git

3. Change into the git reop
   cd intro_git_github

4. Your fork is now your 'origin' remote. Now add this (my) repo as the 'upstream' remote so you can pull other peoples' changes in the future
   git remote add upstream https://github.com/koudyk/intro_git_github.git

5. Start a new branch
   git checkout -b <yourbranch>

6. make a csv file in the folder ssc_workshop called <your_username>.csv
mkdir ssc_workshop
cd ssc_workshop
touch <your_username>.csv

7. list your favorite deserts, with a SPELLING MISTAKE, each separated by a comma.
   To open it: or find the file through your file navigator and open it.
   E.g., you could write in it:

speculaas, ize cream, chocolate

7. save the file

8. (optional) Try inspecting what git is/isn't tracking with git status and/or git status

9. stage the change
   git add <filename>

10. commit the change
    git commit -m "<short, informative commit message>"

11. push the change
    git push origin <yourbranch>

12. Go to your forked version of this repository on GitHub (https://github.com/<your_username>/intro_git_github)

13. Open a pull request

Task 1: Get everyone's favorite desserts!

Get everyone's favorite desserts!

GOAL: practice the workflow of contributing to an open project
TASK: add a file called <your_username.csv> in the folder bhg_2020ish_montreal, containing a comma-separated list of your favorite desserts.
NOTE: replace things inside <> with your own info

0. Comment on this issue saying that you can work on it
1. Fork this repository (icon on top right of this page)
2. Clone your fork to your machine
   git clone https://github.com/<your_username>/intro_git_github.git
3. Your fork is now your 'origin' remote. Now add this (my) repo as the 'upstream' remote so you can pull other peoples' changes in the future
   git remote add upstream https://github.com/koudyk/intro_git_github.git
4. Start a new branch
   git checkout -b <yourbranch>
5. make a text file in the folder bhg_2020ish_montreal called <your_username>.csv
6. list your favorite deserts, with a SPELLING MISTAKE, each separated by a comma. E.g.:

cookies, cake, ize cream

7. save the file
8. stage the change
   git add <path/to/your_username>.csv
   NOTE: slashes in paths go the other way in Windows
9. commit the change
   git commit -m "<short, informative commit message>"
10. push the change
    git push origin <yourbranch>
11. Go to your forked version of this repository on GitHub (https://github.com/<your_username>/intro_git_github)
12. Open a pull request

Task 2b: Open and fix an issue in a collaborative project

GOAL: practice the workflow of contributing to an open project
TASK: fix a spelling mistake in someone else's dessert list
NOTE: replace things inside <> with your own info

0. Find a dessert list with a spelling mistake (we'll pair people up in class)

1. Open an issue reporting the mistake, and saying you'll fix it
   (on this repo, click on Issues, then on the green button New Issue)

2. Assign yourself to the issue
   (on the page with your issue, click "Assignees" on the right, and assign yourself)

3. Label the issue
   (on the page with your issue, click "Labels" on the right, and choose the label that you think is most appropriate. HINT: I made a special label for this task)

4. Wait for the go-ahead from the project maintainer (Kendra)

5. Pull the changes that have been made to the repo by others
   git pull upstream main

6. Checkout a branch for fixing the mistake
   git checkout -b <yourbranch>

7. Correct the spelling mistake in the file on your machine.

8. Add the change
   git add <path/to/filename>
   NOTE: filename slashes go the other way in Windows

9. Commit the change
   git commit -m "fixed spelling mistake in <file>; Fixes #<issue number>"

10. Push the change to your fork
    git push origin <yourbranch>

11. Go to your forked version of this repository on GitHub
    (https://github.com/<your_username>/intro_git_github)

12. Open a pull request

Add Alyssa's favourite drinks

spelling mistake in loic_dishes

Task 1: Track and share your work

GOAL: track and share your own work
TASK: create a local repository, link it to a remote repository on GitHub, and practice changing the repo
NOTE: replace things inside <> with your own info

1. Make a directory somewhere on your machine (make it unique so there isn't another with the same name on GitHub)
   mkdir <your_creative_dir_name>

2. Change into the directory
   cd <your_creative_dir_name>

3. Make a Python script
   touch <script name>.py

4. Write and save something in the file
   To open it: <text editor> <filename> or find the file through your file navigator and open it.
   E.g., you could write print('hello world') in the file.

5. (optional) Try inspecting what git is/isn't tracking with git status and/or git status

6. Initialize a git repository
   git init

7. Stage the change
   git add <filename>

8. Commit the change
   git commit -m "<your short, informative commit message>"

9. Make a repository on GitHub with the same name
   (You might have to wait for it to restart)

   • Go to github.com
   • Click ''Repositories''
   • Click ''New'' (green button)
   • Enter <your_creative_dir_name>
   • Choose to make your repo Public or Private
   • Don't check any boxes
   • Click ''Create repository''

10. Tell git the address of your remote repository
    git remote add <remote> <remote location, i.e., the url of your repo>.git
    It's highly recommended to use origin as your remote name, but you can choose any name

11. Rename the principal branch from master to main
    git branch -M main

12. Push your local repo contents to the remote repo
    git push -u <remote> <branch>
    Note that you only need the -u the first time

13. (optional) To practice, repeat these steps a few times

    • change your file
    • stage the change
    • commit the change
    • push the change to github

Task 2: Correct spelling mistakes in desserts lists

Correct spelling mistakes in desserts lists

GOAL: practice the workflow of contributing to an open project
TASK: fix a spelling mistake in someone else's dessert list
NOTE: replace things inside <> with your own info

0. Find a dessert list with a spelling mistake (we'll pair people up in class)
1. Open an issue reporting the mistake, and saying you'll fix it
   (on this repo, click on Issues, then on the green button New Issue)
2. Wait for the go-ahead from the project maintainer (Kendra)
3. Pull the changes that have been made to the repo by others
   git pull upstream main
4. Checkout a branch for fixing the mistake
   git checkout -b <yourbranch>
5. Correct the spelling mistake in the file on your machine.
6. Add the change
   git add <path/to/filename>
   NOTE: filename slashes go the other way in Windows
7. Commit the change
   git commit -m "fixed spelling mistake in <file>; Fixes #<issue number>"
8. Push the change to your fork
   git push origin <yourbranch>
9. Go to your forked version of this repository on GitHub
   (https://github.com/<your_username>/intro_git_github)
10. Open a pull request

fix typo

there's a typo in kendra.csv file: ize cream --> ice cream. I'll fix it