Git Basics and Resources

Basics

Git is not as scary as it seems I promise.

Resources

This is a great primer for beginners: https://github.com/cs-clarence/git-primer

Great info about branches: https://www.w3schools.com/git/git_branch.asp

Basic commands

assuming you’re using a cli (command line interface, the terminal):

• Make an empty .git file in your current directory, so your version history can start getting tracked for this repository.

git init

• Add the file to your records, or updates the version being tracked. Note that you can press tab to show what files match the path you’ve typed, and stop you from typing the full name forever

git add [file path]

• Make your additions official. This can be undone or rollbacked easily, but if you never commit you can’t get back old work! Don’t be afraid to commit liberally.

git commit -m “Message”

• Put your work up on the remote repo (assumingly on github). If this fails, it will tell you the reason (most likely that you don’t have a remote repo set up. Be not afraid! You can add it with git remote add [repo link])

git push

• Pull (fetches) all files from the remote repo (github) and updates your local repository (on your computer). If you do not include the link, it will assume you are pulling from your pre-configured remote repo. Implies a connection to your current project, and that you may change it.

git pull [link]

• Create a new folder that contains the pulled repo and all its own git history. It will do this in the directory you’re typing it from.

git clone [link]

• Create a new branch of the repo

git branch [branch name]

• Show you what branch you’re on and the other branches you can swap to locally. Does not show all the possible remote branches if you haven’t pulled them.

git branch

• Add everything from the selected branch to your current branch. However, before you do this, you should consider why the merge is needed, and the things that will be impacted. I recommend instead of using this command, do merges using the web gui, so you can review the exact files impacted and add comments more easily. You can also add a reviewer on web, so they can take a look at what will be impacted. Github’s documentation on the topic is here

git merge [branch name]

• Move you over to a branch branch. Does not take your work with you! Make sure you’ve committed.

git checkout [branch name]

• See stuff like your working branch, the tracked files, the untracked files, the new changes, and things that will be added in your next commit.

git status

Best practices

• Never. Never never never neverennevnernenrenvenrner push passwords, login info, or any private key. Please scrub your code of them or (even better) keep them in your environment variables. There are pre-commit hooks like detect-private-key from the pre-commit repo, which can help you with this.
• Don’t push data or a large number of network weights. This takes a long time to upload and a long time to pull and will eventually have us pushing against storage limits of github. Use DeepGotData or Zendo Instead!~
• Use a type of linter or pre-commit hooks.
• Commit often and commit with descriptive comments
• Any major change (function written, new file, any file rewrite) should be committed with a comment of what you did.
• At the end of the day, or just at the end of a session, I recommending pushing your work to a remote (just in case of a catastrophic blue screen of death).
• Always pull before you push.
• If working with a collaborator, on different but potentially similar parts of code, work on different branches.
• Include a .gitignore, that makes sure you don’t track things like pycaches or any other compiled code. This can potentially cause issues when installing on different os’.

Branch Etiquette

• When working alone, working on one branch but with a lot of commits is fine, but it can lead to heartache if you overwrite some big changes. When in doubt, branch.
• When working with a group on a science or experiment based project, each new piece of the project should be a branch.
• When working with project that is in a complete and functional state, but needs updates or feature additions, opening an issue and working on a branch specifically for that branch is best practice.
• New branches in this case follow the below structure. Almost all issues fit into one of these categories and using this label convention helps with uniformity and intelligibility between groups. If you can't figure out what category your work is under, it's probably a feature.

Feature/description-of-added-feature

Bug/description-of-bug-fix

Util/description-of-added-test/engineering-utility

Fix/fixing-something-thats-not-broken

Github Actions

• Github supports something called ‘actions’. Which is basically just a script that’s triggered when you take a… get this… action on github.
• Main docs are here: https://docs.github.com/en/actions
• We have some of them included in the template repos! Check them out!
• They’re fantastic for automatically updating things, or automatically running tests.

If in a panic

https://ohshitgit.com/ 😤