General Github Resources and Glossary
Why Github?
Even if you don’t feel that your code is ready to be shared, it is important that it be backed up somewhere other than your local drive- Github is that place for coding projects! You can create a private repository that is visible only to you and nay Github Enterprise collaborators you designate if you are working on draft products that aren’t ready to share. Using Github does not immediately make your work public!
Not sure why we use github? Check out this illustrated blog post explaining how github is used for supporting, reusing, contributing, and failing.
Github Trainings and Videos
The NOAA Fisheries GitHub Governance Team has an excellent suite of videos on git skills. Check out those videos here.
Github skills for self-guided learning found here.
Guidance and best practices for NMFS github users provided by NMFS Open Science can be found here.
The NOAA Omics Technical Portal has a suite of resources specific to ’Omics data, including example analyses!
The NOAA Omics Discussion Forum may also be a good place to ask and answer questions regarding ’Omics analyses.
Markdown Basics
README files are all markdown files. If you are new to using markdown, check out this cheat sheet.
You can also open and edit markdown documents in R Studio. There is an option in the top corner to change the view form “Source” to “Visual” to view and edit the markdown code as it will be published.
Github Basics Glossary
A full list of terms can be found here, but below are some common terms to get acquainted with.
| Term | Definition |
|---|---|
| branch | A branch is a parallel version of a repository. It is contained within the repository, but does not affect the primary or main branch allowing you to work freely without disrupting the “live” version. When you’ve made the changes you want to make, you can merge your branch back into the main branch to publish your changes. |
| clone | A clone is a copy of a repository that lives on your computer instead of on a website’s server somewhere, or the act of making that copy. When you make a clone, you can edit the files in your preferred editor and use Git to keep track of your changes without having to be online. The repository you cloned is still connected to the remote version so that you can push your local changes to the remote to keep them synced when you’re online. |
| commit | A commit, or “revision”, is an individual change to a file (or set of files). When you make a commit to save your work, Git creates a unique ID (a.k.a. the “SHA” or “hash”) that allows you to keep record of the specific changes committed along with who made them and when. Commits usually contain a commit message which is a brief description of what changes were made. |
| directory | A folder containing one or more files or folders. You can create directories to organize the contents of a repository. |
| fork | A fork is a personal copy of another user’s repository that lives on your account. Forks allow you to freely make changes to a project without affecting the original upstream repository. You can also open a pull request in the upstream repository and keep your fork synced with the latest changes since both repositories are still connected. |
| pull | Pull refers to when you are fetching in changes and merging them. For instance, if someone has edited the remote file you’re both working on, you’ll want to pull in those changes to your local copy so that it’s up to date. |
| pull request | Pull requests are proposed changes to a repository submitted by a user and accepted or rejected by a repository’s collaborators. Like issues, pull requests each have their own discussion forum. |
| push | To push means to send your committed changes to a remote repository on GitHub.com. For instance, if you change something locally, you can push those changes so that others may access them. |
| repository | A repository is the most basic element of GitHub. They’re easiest to imagine as a project’s folder. A repository contains all of the project files (including documentation), and stores each file’s revision history. Repositories can have multiple collaborators and can be either public or private. |