Committing Code

Before calling the API to commit a revised README file to a software project on GitHub, you first need to step back and look into Git's inner workings. Under the hood, Git relies on a few simple but powerful data structures, although the git command-line tool completely shields them from regular users. Git represents a file in the repository as a so-called blob. A collection of these blobs in a directory is called a tree, and a tree with a check-in note is a commit (Figure 6). A thorough introduction to Git's guts can be found online [5].

Figure 6: Under Git's hood, commits consist of trees, whereas trees contain blobs and other trees.

Before the script in Listing 6 can commit to the test project mschilli/apitest, I first need to collect a new token with escalated privileges. The token obtained in Listing 1 only let me read the repository data. To gain write access, line 15 in Listing 1 must be replaced by

scopes => ['public_repo'],

and the comment stored in the note parameter needs to be changed. A new call to token-get then stores a new token with advanced privileges in the token file.

Blobs, Trees, Commits

The call to the readme-upd script (Listing 6) then generates a new blob of the README file with permissions of 0644 and defines a tree to store the blob. On top of this is the base_tree option in line 40, set to an already existing tree in the repository, which the script extracts from the most recent commit of the master branch. Basing the new tree off this base tree ensures that any other existing files will stay in the newly created version of the repository.

Line 43 then converts the tree into a commit, with a fun date of 11/11/2011, which illustrates that date and author information in Git can be arbitrarily set.

Showing Pointers

Previously, line 19 of the listing retrieved the references to the development branches of the repo. After the new commit is in place, line 54 redirects the head pointer of the project's master branch to it. This can be accomplished without using force (force => 0) because the new commit was derived straight from its ancestor. Figure 7 shows what the automatically injected commit looks like on the GitHub website of the project.

Figure 7: Shortly after the commit was created by script, it is visible on the GitHub website.

When this issue went to press, version 0.71 of the Net::GitHub module still had a bug in its implementation of update_ref(). However, a quick pull request provided a remedy [6]. With a little bit of luck, the module author will have already added the patch in the latest release, which will be on CPAN by the time this article is published.

If you want, you can run one of the query scripts in this article as a daily cronjob to create a timeline that illustrates how hard you have been working on your GitHub projects day in and day out. Or, perhaps the boss would like to be alerted if an employee suddenly experiences a sudden productivity boost.