GitHub Fundamentals for OBO Engineers
Introduction to GitHub¶
GitHub is increasingly used by software developers, programmers and project managers for uploading and sharing content, as well as basic project management. You build a profile, upload projects to share and connect with other users by "following" their accounts. Many users store programs and code projects, but you can also upload text documents or other file types in your project folders to share publicly (or privately). It is capable of storing any file type from text, to structured data, to software. And more features are being added by the day. The real power of Git, however, is less about individuals publishing content (many places can do that, including google docs etc). It is more about that content being easily shared, built upon, and credited in a way that is robust to the realities of distributed collaboration. You don't have to know how to code or use the command line. It is a powerful way to organize projects with multiple participants.
Git supports the following types of primary entities:
- Individual: A person who contributes to GitHub (that's you!)
- Example individual http://github.com/nicolevasilevsky
- Organization: An entity that may correspond to an actual organization (such as a university) or to a meaningful grouping of repositories. Organizations are like individuals except that they can establish teams.
- Example organization: https://github.com/monarch-initiative
- Repository: A collection of versioned files (of any type)
- Example repository https://github.com/monarch-initiative/mondo/
- Teams: A group of individuals assembled by the administrators of an organization. An individual may participate in many teams and organizations, however a team is always bound to a single organization. Nesting teams saves time; instructions here.
The relationships between any combination of these entities is many-to-many, with the nuanced exception of repositories. For our purposes today we will oversimplify by saying that a repositoy belongs either to a single organization or to a single individual.
Content in GitHub is written using Markdown, a text-to-HTML conversion tool for web writers (ref).
For more help with Markdown, see this GitHub guide.
|Raw markup syntax||As rendered|
||# Header, ## Header (note, the header is not displaying properly in this table)|
||Emphasis, aka italics, with asterisks or underscores.|
||Strong emphasis, aka bold, with asterisks or underscores.|
||Combined emphasis with asterisks and underscores.|
||Strikethrough uses two tildes. ~~Scratch this.~~|
To introduce line breaks in markdown, add two spaces For a bulleted list, use * or - (followed by a space)
Here is an example of a list:
Here is an example of a bulleted list: - One - Two - Three
GitHub can store any kind of content, provided it isn't too big. (And now even this is possible). However, it is more capable for some filetypes than it is for others. Certain filetypes can be viewed 'natively' within the GitHub interface. These are:
- Images: png, jpg, svg
- CSV, TSV (note that files named type '.tab' will not render properly in the UI.)
- Software code (eg. including json, HTML, xml etc)
Task - create a new GitHub repository¶
- Create your GitHub account if you do not already have one
- Customize your avatar if you haven't already
- Go to settings and upload any picture (it doesn't have to be your face)
- Create a repository
Task - update the content in your README¶
- Go back to the repository you just created
- Click the pencil icon in the right corner of your README.md file
- Add some content to your file that includes a header, italics, bold, strikethrough, and lists
- You can preview your changes before committing by clicking 'Preview changes'.
- Commit your changes by clicking the commit button at the bottom of the page.
Task - add content to your repository¶
- Click on the code button
- Click upload file
- Upload a file by dragging and dropping or browse for file
- Trying uploading an Excel file vs a TSV or CSV file. How are these displayed differently?
- Frequently Asked Questions
- Git and GitHub for Documentation
- Markdown Cheatsheet
- Git 101: Git and GitHub for Beginners
- Mastering Issues (10 min read)
Adopted from CD2H MTIP tutorial