See all workshops...

Goals

My goal for this session is to provide you with a brief introduction to GitHub. You will be introduced to the concept of source control and tools such as Git and GitHub. By the end of the session you will be able to create your own repository from scratch and work with repositories created by others.

Source Control, Git and GitHub

Source Control, also known as version control, is the management of changes to documents, computer programs, large web sites, and other collections of information. Source control can occur on a small scale such as using track changes when editing a word document, or on a large scale, like a website with multiple pages and sub-pages. The more complex the information environment, the more likely you will need some sort of tool to get a handle on your information. There are many tools, both proprietary and open source, that are available for source control. One example is Git.

Git, http://git-scm.com/, is a free and open source distributed version control system designed to handle everything from small projects to very large ones. Git is completely command line based (as opposed to point and click-based). Command line-based programs are not everyone’s cup of tea, but that’s where GitHub can save the day.

GitHub, http://github.com, is a web-based Git repository hosting service with all of the revision control and source code management of Git plus some added features. GitHub provides a web-based graphical interface and desktop client as well as mobile integration. Use of the command line is optional. GitHub is widely used as tool for projects in multiple disciplines, including the humanities. For some examples visit the Heard Library’s repositories on GitHub: https://github.com/HeardLibrary

Why Would I Want to Use GitHub?

GitHub may describe itself as the place where software is built, but software developers and computer programmers are not the only people using GitHub. Scholars in all disciplines are using GitHub to build digital projects, share data, and even using GitHub in the classroom. Below are some examples:

Digital Projects

Open Greek and Latin Project, https://github.com/OpenGreekAndLatin Produces machine-corrected XML versions of Greek and Latin works and translations.

Syriaca.org: The Syriac Reference Portal, https://github.com/srophe A collaborative research project publishling online reference works concerning the culture, history, and literature of Syriac communities from antiquity to the present.

LOGAR: Linked Online Gazetteer of the Andean Region, https://github.com/sawernke/gazetteer-demo

Corpus Baudelaire, https://github.com/HeardLibrary/corpus-baudelaire TEI encoding of Baudelaire’s Le Fleur du Mal.

GitHub in the Classroom

GitHub Education, https://education.github.com/ Free and discounted plans for educational use. Faculty are using GitHub instead of a traditional course managment system (Blackboard, Moodle, Sakai) or using Github as a submission platform for student assignments.

Related Readings

The Emergence of GitHub as a Collaborative Platform for Education http://alexeyza.com/pdf/cscw15.pdf

Push, Pull, Fork: GitHub for Academics http://www.digitalpedagogylab.com/hybridped/push-pull-fork-github-for-academics/

COMP 116: Introduction to Computer Security, https://github.com/tuftsdev/DefenseOfTheDarkArts Course website for COMP 116: Introduction to Computer Security.

The Basics of Markdown

To get the most out of GitHub, you will need to learn some Markdown. Markdown, http://daringfireball.net/projects/markdown/, is a lightweight and easy-to-use syntax for styling all forms of writing on the GitHub platform. Click on this link for a handy cheat sheet on Markdown syntax.

You can use Markdown to:

• Create a Gist - a quick and easy way to share snippets of code with collaborators
• Add comments in Issues and Pull Requests
• Editing the repository Wiki
• Create files with a .md or .markdown extension such as the repository Readme.md file

GitHub.com uses its own version of the Markdown syntax that provides an additional set of useful features, many of which make it easier to work with content on GitHub.com. Visit the Mastering Markdown guide to learn more about GitHub-flavored markdown.

Getting Started with GitHub

GitHub is free to use for public projects. A free account gives you the ability to create an unlimited number of public repositories with an unlimited number of collaborators. GitHub also offers a number of personal and organizational plans for those who need to collaborate on private repositories. More information about plan pricing is available here.

Creating your free account is the first step to mastering GitHub.

Now that you have an account you can quickly and easily edit your public profile and other settings by clicking on the edit profile button or selecting settings from the drop down menu in the top right corner next to your profile image.

You can manage all of your personal settings from this screen including your public profile, account settings, emails, notifications and more!

Creating a New Repository

You can create a new repository in one of two ways. You can click on the + next to your profile image in the top right corner of the screen or go to the repositories tab within your profile page and click the New button.

Now that you have committed to creating a new repository there are just a few more easy steps to initialize your repository:

1. Name it - Always keep it short and sweet.
   • Let’s create a repository named Hello-World
2. Describe it (optional)
3. Select Public for your repository status
   • Remember public repositories are free whereas private repositories require a billing plan
4. Check the box to initialize your repository with a README
   • Every repository needs one!
5. Click Create Repository!

Playing with Your New Repository

We will explore three concepts using our new Hello-World repository: Creating an Issue, Branching and Creating a Pull Request.

Issues

An Issue is a note on a repository about something that needs attention. The Issue could relate to a bug, a feature request, or any questions you might have. You are basically creating a conversation between you and your collaborators.

Try this feature out by opening an Issue about README edits by clicking on the Issues link in the column on the right and then clicking on the green New Issue button on the following screen.

In the Issues pane you will need to create a title for your Issue, and you can describe it in further detail below. In this case we will create an issue about adding more detail to the README file.

You can also use the features in the column on the right to add a label describing the issue, a milestone (this associates your issue with a particular feature or phase of your project), or assign the issue to one of you collaborators.

The last step is to click the green Submit Issue button to officially create your issue.

Branching

Branching is the way to work on different parts of a repository at one time. By default all new repositories are created with one branch named master. You can work within your master branch, but creating working branches allows you to develop a feature or idea and work out all the bugs before merging it into master(your production branch).

Using a working branch can save you a great deal of heartache during the development process. You can fail repeatedly and spectacularly in a working branch without impacting your master branch.

To create a branch go to your new repository hello-world and click the drop down at the top of the file list that says branch: master, and create a branch named readme-edits:

We are currently in our working branch readme-edits, let’s edit our README file by clicking on the README file and then clicking on the pencil icon in the upper right corner of the file view to edit. Make a change to the file and commit it! On GitHub, saved changes are called commits. Each commit has an associated commit message that describes the change being made and why. These commits document the history of the repository.

Pull Requests

Pull Requests are the key to collaboration on GitHub. Using a pull request, you are proposing changes and requesting that someone pull in your contributions. In GitHub, pull requests allow you to compare the content of two branches. The changes, additions, and subtractions are shown in green and red and called diffs.

Think of pull requests as a way to start a conversation where you can get feedback on the development process. You can also use GitHub’s @mention system to ask for feedback from specific people.

We are going to open a pull request for our own repository and merge it ourself for practice. Click on the Pull Request icon in the side bar on the right. With our pull request, we can also closed the Issue about the README file we opened earlier. In the comments section of pull request, include the following text fixes # and number of the issue which in this case is 1.

The last step is to put it all together and merge your readme-edits branch in the master branch. Once your merge is complete you can delete your working branch.

+

Everything we have done so far has been in the web client of GitHub. To work offline, you will need to install the GitHub desktop client, which we will discuss in more detail below.

Working with a Forked Repository

Building your own repository can be fun, but sometimes you just want to contribute to an existing project or maybe you would like to use someone else’s project as the starting point for a new project of your own. If that is the case it is time to Fork.

Creating a fork creates a personal copy of someone else’s project. You can submit Pull Requests to help make other people’s projects better by offering your changes up to the original project. We are going to create a fork of the Spoon-Knife repository created by octocat.

Navigate to the page for the Spoon-Knife repository, and click the Fork button in the header of the repository.

We have been able to make edits to our repository files in the web version of GitHub, but that can get tricky. Installing the GitHub desktop client gives us more flexibility in how we can interact with the documents and files within our repository.

Download GitHub Desktop (available for MAC and PC).

Now that you have successfully installed GitHub Desktop and forked the Spoon-Knife repository, it is time to get to work. Currently your fork of the Spoon-Knife repository only exists on GitHub, but we need to clone it to your computer.

Navigate to your fork of the Spoon-Knife repository. Click on Clone in Desktop in the right hand side bar.

Once you have successfully cloned the repository, all the repository files will be available to you on your desktop. We can open a text editor (you can use any text editor, but I recommend installing ATOM and make some changes to the index.html file in the Spoon-Knife repository.

Remember to create a working branch first!

Commit your changes and then click on the Sync button to push your changes from the desktop client to GitHub.com.

Currently, the changes you made are only part of your forked repository. Now it is time to propose changes into the main project by octocat.

Go to your fork of the repository on GitHub.com and click on the green Compare and Pull Request button located next to your branch to initiate a pull request.

Once you have submitted the pull request it is up to the project owner whether your changes will be pulled into the repository or not.

Success! You are now a GitHub user!

For more helpful tutorials about using GitHub visit GitHub Guides https://guides.github.com/