Working with GitHub

GitHub is a way to keep track of your code for a project, while also allowing a team to work independently on the same project. It is a bit unintuitive to use; it combines using a web browser with command line functions (through the Mac terminal, or Windows Command Line).

Installing Git (one time only)

Macs: Install Xcode, which will include Git automatically
xcode-select --install

Windows: https://git-scm.com/download/win

To check to see if the installation was successful, run:
git --version

Getting onto GitHub (one time only)

1. Create an account on GitHub https://github.com/
2. Create a SSH key for GitHub: (Do this on each computer that you own (not in a computer lab) will be using regularly)

   https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent?platform=mac

   • Notice that there is a tab to change the instructions to Windows or Linux.
   • I recommend setting up a passphrase (a password) to secure your computer even more.
3. Follow the "Generation a new SSH key" and the "Adding your SSH key to the ssh-agent" sections.
4. Then, follow the "Adding a new SSH key to your GitHub account"

   https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account

   • Key type: Authentication Key

Cloning the repository (the first time you are working with a new project, i.e. a new code repository)

1. If needed, ask Eric for access to the proper repository.
2. Log onto GitHub and navigate to the repository that you are working on. For example:

   https://github.com/MEE-Laboratory/single-species-simulation-eric-niki-and-yuko

3. Clone the repository
   • Click on the green "<> Code" button
   • Select SSH
   • Copy the resulting link
   • On your terminal:

   git clone <clone link>

   • All of the code in the repository is now downloaded to your local computer, in a folder with the repository name.

Making changes to a repository

Making changes to a file on your local computer, i.e. work on your code

• You should see a new directory named after the repository on your own computer. You can then edit this document in a text editor. I suggest Sublime Text (https://www.sublimetext.com).

• You can test your code locally by:
  • Use the terminal to move to your repository folder

python <name of the file you want to run>

Please note: your file must be saved in the text editor before python 'sees' the changes!

Updating your code back to the repository on GitHub

• Use the terminal to move to your repository folder
• Check the status of the repository
  • git status
• Check the logs of the file (seeing what others have changed, for example)
  • git log
  • git log --oneline

Single files, destroying what was on GitHub

This is best for if only one person is working on a project. It clobbers / overwrites the previous file, so it is not best if more than one person is working on the project.

1. Use the terminal to move to your repository folder
2. Add a file to the staging area

   git add [file-name]

3. Add all new and changed files to the staging area

   git add -A

   However, your changes are not permanent until you commit them. This uploads them back to the online repository

4. Commit changes

git commit -m "add a small description of the change"

Resetting and Reverting changes

• resetting a certain number of commits (after reviewing the log)
  • git reset --soft HEAD~<number of commits to undo>
  • use --soft to uncommit and keep staged changes
  • use --hard instead to uncommit and delete changes

Each change in the log as a number/letter hash associated with it. To uncommit that change, copy this hash.

• git revert <commit hash>

Branching: creating a working copy of code

• Previewing changes before merging branches:

git diff [new branch] [old branch]

• List branches (the asterisk denotes the current branch)

git branch

• List all branches (local and remote)

git branch -a

• Create a new branch

git branch [branch name]

• Delete a branch

git branch -d [branch name]

• Delete a remote branch

git push origin --delete [branch name]

• Create a new branch and switch to it

git checkout -b [branch name]

• Clone a remote branch and switch to it

git checkout -b [branch name] origin/[branch name]

• Rename a local branch

git branch -m [old branch name] [new branch name]

• Switch to a branch

git checkout [branch name]

• Switch to the branch last checked out

git checkout -

• Discard changes to a file

git checkout -- [file-name.txt]

• Merge a branch into the active branch

git merge [branch name]

• • If there is a conflict, resolve it manually. This change needs to be commit-ed to save the resolved merge.

• Merge a branch into a target branch

git merge [source branch] [target branch]

Sharing and updating the online repository

• Push a branch to your remote repository

git push origin [branch name]

• Push changes to remote repository (and remember the branch)

git push -u origin [branch name]

• Push changes to remote repository (remembered branch)

git push

• Delete a remote branch

git push origin --delete [branch name]

• Update local repository to the newest commit

git pull

• Pull changes from remote repository

git pull origin [branch name]

Starting your own repository (not on GitHub)

git init

Example workflow

• Get the latest code

git pull

• Create a new branch (called testing2 here) and check it out. Alternatively, if you are already working on a branch, you can use git checkout branchName instead.

git checkout -b testing2

• At this point, open up your code in a text editor and modify it. Remember to save!
• When you are done, we need to add it to GitHub, and commit it. Add a better comment than "blarg"!

git add SingleSpeciesSimulation.py

git commit -m "blarg"

• OK, so we now need to merge the branch back into main, if you are ready to permanently work with these changes; this moves your work from your branch to the main code. We checkout the main branch, merge, and then push the changes.

git checkout main

git merge testing2

git push