1 of 30

git and GitHub

Presented at WHOI Python Carpentries 2024-06-28

Till Hoffmann (thoffmann@hsph.harvard.edu)

Department of Biostatistics

Harvard T.H. Chan School of Public Health

2 of 30

What is git?

3 of 30

Artwork by @allison_horst

4 of 30

Artwork by @allison_horst

5 of 30

Artwork by @allison_horst

6 of 30

Installing git

https://git-scm.com/downloads

7 of 30

ls -l --human-readable .

Recap: structure of shell commands.
Shell commands comprise two parts the command itself (ls in this case) and the arguments (everything else).
It's up to the command to interpret the arguments; they are simply strings and, unlike Python, have no type.
For consistency, most commands follow conventions (but they're not rules, and some commands have unconventional arguments). Specifically,

arguments starting with -- like --human-readable above are long-form options. They modify the behavior of the command but are not required.
arguments starting with - like -l above are short-form options. They usually, but not always, have a corresponding long-form option but save you a few keystrokes.
arguments without leading dashes are positional arguments and often specify what the command should operate on, e.g., the path to files that rm should delete.

Do not use spaces in filenames. At best, you have to remember quotation marks around filenames or escape spaces with my\ file\ name. At worst, you end up with buggy code. For example, the popular make command does not handle spaces well. Don't use spaces.
Tangent: Use relatives paths whenever you can. If you use absolute paths like /Users/[your name]/data/…, it is not easily possible to share your code with colleagues (unless you have a name twin).

8 of 30

Artwork by @allison_horst

9 of 30

😬 Live Coding

10 of 30

What's happening here?

pwd: We print the current working directory to ensure we know where we are.
mkdir whoi-git-example: We create a new directory which will serve as our repository.
cd whoi-git-example: We change our working directory to the newly created folder and …
pwd: … check that we are in the right folder.
git init: We initialize a new, empty git repository as the output of the command indicates.

We create a new directory to isolate any changes we make in the repository from the rest of your system. Any subsequent git commands will only ever act on files in this directory. E.g., you can accidentally delete all the content of the repository if you use the wrong git command, but you won't be able to accidentally wipe your photo library or thesis draft.
Depending on the version of git you are using, you may receive a warning: Using 'master' as the name for the initial branch. This default branch name is subject to change. Computer science has a few terms that needlessly use language related to slavery, e.g., master-slave architectures. In 2020, the default branch name was changed from master to main (see the official announcement here). You can check your default branch name by running git branch, and you can rename your branch to main by executing git branch -m main.

11 of 30

✨ Creating Your First Commit

12 of 30

13 of 30

Artwork by @allison_horst

14 of 30

15 of 30

git config --global user.email "boaty@mcboatface.com": Set our "email address" to the Autosub Long Range class AUV. Use your own email address. This can be either your personal email address or your institutional email address.
git config --global user.name "Boaty McBoatface": Set our name like above. This can be either your full name, your GitHub username (if you have one), or your coding artist name.
git commit -m "Add README.md.": Commit the file, finally.
git status: Check that the file was successfully committed. The working tree (our directory) is clean, and there is nothing left to commit.

If you work on many different projects for different institutions, you may want to use different emails in different repositories. You can achieve that by executing the relevant git config … command for each repository without including the --global option to set per-repo username and email.

16 of 30

17 of 30

➕➖ Diffs and Your Second Commit

18 of 30

19 of 30

20 of 30

21 of 30

Artwork by @allison_horst

22 of 30

Creating a New Repo

Create a GitHub account at https://github.com/signup if you don't have one.
Create a new repository named whoi-git-example at https://github.com/new.

Let's create an account if you don't have one already.
Create a new, empty repository. Let's call it whoi-git-example, but you can pick any name you like.
There are a few choices, but let's leave them at their default values. The main ones are:

Should the repository be public (anyone can see it) or private (only you and any collaborators you add can see it)?
Do you want to prepopulate the repo with a README.md file? No for us, because we've already manually created one.
Do you want to add a .gitignore to the repo? Let's leave it for now, but .gitignore files can be useful if you want to exclude certain files or file types from the repository. For example, maybe there are sensitive files you don't want to accidentally publish to GitHub or store in git.
Do you want to add a license file? Adding a license is useful to indicate how you want your code to be used and, depending on the license, can also protect you from liability (see here for more details).

23 of 30

Artwork by @allison_horst

24 of 30

25 of 30

26 of 30

Creating a Token

Create a new Personal Access Token at https://github.com/settings/tokens/new.
Select repo scope.

27 of 30

28 of 30

🚀

29 of 30

30 of 30

🏃 Next Steps

Create separate branches, pull requests, and collaborate with GitHub flow.
Create i ssues for feature requests and bugs.
GitHub Actions and automatic testing.
README, LICENSE, and CONTRIBUTING.
Set up authentication with ssh.
Ignore files using .gitignore.
Get your code cited using CITATION.cff.
Use the cheat sheet.