Intro to version control with git & GitHub
===

## Description
Created: 2023-05-19
Updated: 2023-05-19

Tutorial for PHIRE 2023:
- Learning basic version control with git/GitHub, loosely following the [Software Carpentry lesson](https://swcarpentry.github.io/git-novice/04-changes.html).

# Thursday 5/18/2023
## Codespaces with Git & GitHub
Rather than doing everything through command line interface, it's much easier to use the GUI/point-and-click, but the workflow cycle is still the same.

Steps:
1. Log in
2. Click `Codespaces` from menu at the top of your window
3. Use a Jupyter Notebook template to quick start your `codespaces` virtual machine
- run `ls -la`, notice the `.git` directory that is in your folder structure
4. open `notebooks/population.ipynb` from the file explorer
5. Insert a Markdown chunk anywhere in the notebook with a note to yourself
- run the chunk!
6. Click the source control icon from the hamburger menu on the left of your `codespaces` window
7. Click the "+" to "add" your changes to the git stage
8. Write a commit message in the provided window
9. Commit!
- check `git log`
10. Next, publish this repo to a GitHub repository (public or private) with "publish branch"
- check your github for your new repo!

## Via command line interface
Basic workflow of commands:
1. `git pull`: pull changes from the remote repository (make sure that the remote and local repository match each other; important when working with multiple collaborators).
2. Change files on your local machine.
3. `git status`: see what files have been changed.
4. `git add`: stage files
5. `git commit -m "Your commit message"`: commit the changes with an accompanying message
6. `git push`: push the changes to the remote repository.
7. `git log`: see the log of previous commits.

# Friday 5/19/2023
## Download to personal machine
Download GitHub Desktop: https://desktop.github.com/
Download VS Code: https://code.visualstudio.com/
Download git: https://git-scm.com/downloads

## Creating a new repository from GitHub
Public vs. private repositories
- You can switch between private versus public under the repository Settings, but if you have already published something from a public repository (such as a webpage), you cannot make the repo private.

`README.md` file
- Generally good practice to add, include a description about the repository and how others can interact with it.

`.gitignore` file
- A `.gitignore` file is a text file with a list of files, folders, and file extensions that `git` will always ignore (will not not track, and will not prompt you to stage the file).
- Chose from a template, based on your project's programming language. You can always edit this later.

Choose a license
- A license helps others understand how/when they can use your code and how to attribute it to you.

## Create a Wiki page from your repository
1. Go to your repository.
2. Click the Wiki button.
3. Create the a page.
4. Editing the page - the default is using [Markdown](https://www.markdownguide.org/cheat-sheet).
5. Save.

Examples:
- https://github.com/clizarraga-UAD7/PHIRE2023/wiki
- https://github.com/lossanna/phire-example/wiki

## Using GitHub Desktop and VS Code on local machine

### Cloning to local machine
Clone your GitHub repo to your local machine via GitHub Desktop, and then edit in VS Code.

1. Open GitHub Desktop
2. Clone your example repository (File --> Clone repository)
3. Repo should automatically open. If not, open repo.
4. Click "Open in Visual Studio Code" button.
5. Switch to VS Code.

### Committing changes from VS Code

1. Open repo in VS Code.
2. Click Source Control on the lefthand side - you should see a box where you can write a message, and a blue button that says Commit.
3. Make changes to files on local machine.
4. See what files have changed in the lefthand panel. Untracked files will be marked with a bold U.
5. Stage the files by clicking the + button.
6. Write a commit message in the box.
7. Commit and push changes to GitHub.

## Committing changes from GitHub website