Push, Pull, Fork: GitHub for Academics

Push, Pull, Fork: GitHub for Academics

In his article, “Open-source Scholarship”, Kris Shaffer argues that the open-source software model has lessons to offer the academic community. Here, Kris demonstrates how a scholar can put open-source philosophy into practice using a specific tool developed by and for the community: GitHub.

One of the chief goals of liberal education is the creation and curation of human knowledge. As I discussed in my previous article, this necessarily involves critiquing and building on the work of others, and doing so publicly and accessibly. How can we as a community of scholars facilitate this work? How can a scholar or pedagogue make an article, an assignment, a syllabus, a book, a database, or a website available for others in a manner that makes it easy for another to rework and redeploy? Putting a PDF on a website is not enough, even for materials of moderate complexity. We need tools that make it relatively easy to put the ideology of liberal education into practice, from the simple class assignment to the multimedia textbook. One such tool is GitHub.

Though not designed specifically for academic use, GitHub is designed with text, sharing, collaborating, and freedom in mind. For those looking to “hack” existing work, to offer their own materials for others to hack, to collaborate with others, and particularly to do so with websites, software, or complicated text resources, GitHub is an amazing resource. And due to its social, collaborative nature, it is a resource that is consistent with the ideology of liberal education, and will grow in utility the more our academic communities make use of it.

GitHub was created as an online host for software code. Developers who want to share their code with the world can host it on GitHub, and groups of developers who want to collaborate on a project can use GitHub as their central base for sharing code. Any open-licensed project can be hosted on GitHub for free, and GitHub makes its money by charging users for hosting closed-source projects in private repositories, and by offering services and analytical tools. GitHub uses Git, a multi-platform version control application created for use by developers of the Linux kernel, to coordinate collaborations and to manage uploads and downloads (pushes and pulls) to GitHub. Though developed for software code, any types of files can be part of a GitHub repository, and any text-based files (including plain text, MarkDown, HTML, LaTeX, and LilyPond music notation software files) can take advantage of Git’s amazing version tracking and “merging” features. GitHub is also a kind of social network, providing collaborators an easy way to discuss issues in a project, and to follow other users and projects of interest.

Because GitHub hosts open-licensed projects and is designed for collaboration, GitHub allows any user to fork any public project. By clicking the “fork” button, any GitHub user can almost instantaneously create their own version of an existing project. That “forked” project can be used as the basis for a new project, or can be used to work out new features that can be merged back into the original.

GitHub also offers a non-standard form of website hosting, which is where much of the power for academics lies. Any GitHub repository can have its own wiki and its own project website. Further, any project can be its own website. In other words, the GitHub project that can be the focus of sharing and collaboration can be a website, hosted on GitHub. Thus, a GitHub website is not only an open-source tool. It is a publishing platform, a peer-review system (both for the purpose of revision, and for the purpose of evaluation: for example, which users and projects/publications get the most forks?), an LMS, and a locus for intra- and inter-institutional collaboration.

The ProfHacker blog at the Chronicle of Higher Education has posted a number of tutorials on GitHub, most recently Konrad Lawson’s GitHub101 series. I won’t reproduce all of that here. Instead, I will demonstrate the capabilities of GitHub for open-source academia using a website I created for my Musicianship courses at Charleston Southern Univ. that substitutes for a textbook.

I decided to build this website as I found myself working around, supplementing, or even replacing more and more of the chapters in the textbook I had chosen for the course. Not only are there newer, more helpful approaches to the course material that have not yet made it into any published textbook, but the standard textbooks all have a lecture-then-homework model in mind. I’ve found that a different kind of resource is best for the inquiry-first, inverted-class approach that I take. Further, I wrote these resources for a specific group of students, with specific class activities in mind, from the perspective of a specific school of thought — none of these things are possible in a textbook written for tens of thousands of students at hundreds of universities in dozens of countries. I also wanted to share this website with other music theorists at other universities. They have different students (with different majors and areas of concentration), different class activities, and come from the perspectives of different schools of thought.

I originally began building this website in WordPress. I love WordPress — it’s open-source, easy to install, easy to use. However, this project outgrew WordPress. WordPress is great for building a site for my classes, and for sharing that content with others, but it does not facilitate sharing with others who will need to modify the content. Even though each page had a Creative Commons license at the bottom, any instructor who wanted to modify the content would have to build a new site from scratch, and then copy, paste, and edit the material. This can be an arduous process. GitHub offered a simple way both to publish the material and to share it with others who may want to modify it. And on May 15, my Musicianship Resources website received its first fork from another music theorist who will use it as the home of his online course materials.

As the above video demonstrates, the forking process is simple. And learning the required Git commands should take far less time than building a new WordPress site from scratch and importing content from another site! (Readers unfamiliar with the command line can begin with Lincoln Mullen’s article, “Getting Comfortable on the Command Line.”) In fact, the following list of commands will cover most of what an academic would need to know in order to fork a website, clone it to her local computer, make edits, and update the site.

  • git clone URL – This command will clone a git repository (insert the appropriate GitHub URL) onto a local machine.
  • git add filename – This command will add a new file to the local working directory (where files go before changes are committed).
  • git add . – Using . instead of a filename will add all files in the current directory (recursively) to the working directory.
  • git status – This command will list all files ready to be committed, as well as files not being tracked by git (will not be committed to the project).
  • git commit -m ‘insert notes here’ – This command will commit the new or changed files that were added into a new version of the project. Once a new version has been committed, it can be pushed to the server.
  • git commit -am ‘insert notes here’ – Adding the a option will delete any files from the committed version that were committed from the local directory. (I recommend using this as a rule, so local and remote versions are identical.)
  • git push origin master – This command will take all committed changes from the local version of the project and upload them to the GitHub repository from which it was cloned. This works for a file or set of files (a syllabus, article, etc.), or a user website (one that lives at username.github.io). Only changes will be uploaded, so this is usually a fast operation even for large websites.
  • git push origin gh-pages – This command does the same for a GitHub project website (one that lives at username.github.io/projectname).
  • git pull origin master/gh-pages – If the local version is missing something that is on the server (for example, if you work from multiple computers, or collaborate with a colleague), you need to pull it to your computer before you can push anything new. Pull is technically a combination of the fetch and merge commands, which do exactly what they sound like they do. Since git merge can handle the Linux microkernel, it is nearly flawless for scholarly and pedagogical materials!
  • git log – Use log to view the version history of a repository. (Note that it opens the log in a command-line text editor. On Mac or Linux, use the up and down arrows to navigate. Type q to quit.)
  • git reset –hard versionNumber – Git stores all previous commits in a hidden file inside the repository. If you accidentally break something, use log to find the version to which you want to roll back, and use reset to revert back to that version.
  • Other commands worth exploring for more advanced and collaborative uses are git branch, git checkout, git merge, git diff, and git init (for projects begun and/or living entirely on a local machine).

If you are the only user working on a project from a single computer, once you’ve cloned the initial project, all you need is git add, git commit, and git push. It’s quite simple. But Git and GitHub also allow for far more involved and collaborative work.

So slap an open license on that syllabus, that assignment, that article draft, that grad school seminar paper, that primer you wrote for your students that you wish was in the textbook, and push it to GitHub! Then fork someone else’s project, make it better, and send them a pull request. Push, pull, fork — the open-source way to create and curate human knowledge.

[Photo by jared]

About the Author

Kris Shaffer (@krisshaffer) is Instructor of Music Theory at the University of Colorado–Boulder. His research interests include computational analysis, popular music analysis, new-form scholarly publishing, and the pedagogy of music theory and musicianship. Kris can be found on the open web at kris.shaffermusic.com and on GitHub at github.com/kshaffer.

One Comment
Discussions from the Community.
  1. Justin Longo says:

    Kris – I am very glad to have found this excellent intro to using GitHub for open academic collaboration. We’re now exploring the use of GitHub as a platform for open collaboration with two experiments:

    - Honest PI : this is a test setting designed to provide an opportunity for a wide range of contributors to come together around a pretty accessible topic with many facets: the objective is a journal-ready version of an earlier blog post from our Center (“What’s an honest policy informatician to do?”) that looked at the challenge of opening governance when we have trouble agreeing on “the facts”, and when beliefs and perspectives influence how people interpret facts in public policy discussions; and,

    - GitHub Experiment : this is a research paper that will observe and report on the process of writing the first article.

    This post will be especially useful in the second article, but will also be helpful for contributos learning to navigate GitHub.

    Both articles will be written entirely within the GitHub platform, and are truly open in that anyone, regardless of credentials, can join as a co-author on either or both of these articles. We are approaching this experiment in an exploratory fashion: while we are aware of some examples of the use of GitHub for collaborative writing, we are not aware of many truly open collaborative writing efforts built on Git that have succeeded.

Leave a Comment Join the fray.