Skip to main content

Chapter 4 In Control

We now turn to the situation where your book may have numerous collaborators. Maybe your book is an anthology of short stories with thirty contributors, or maybe it is a human anatomy textbook with the potential for students to discover small errors for many, many years down the road. If the anatomy textbook has four authors, you might begin as colleagues as in Chapter 3, but later may have specialists reviewing and editing select chapters, until finally the book is published and students suggest changes and corrections for the inevitable Second Edition. git is flexible enough to help you at every step.

So the model here is a select few that are in control of the repository. They might be called authors or editors, but we will refer to them generically as overlords (WordNet: “a person who has general authority over others”). In our opinion many projects should be large, because you want to encourage people to contribute.

Large projects use a model similar to this one. Sage, an open source computer algebra system, has hundreds of contributors with a single release manager as the overlord. Reviews of proposed branches are distributed among the contributors themselves, so if the release manager is familiar with the reputations and expertise of members of the community, it can be feasible for a single person to roll up fifty or so contributions on a weekly basis and still maintain the integrity of the project, and their sanity.

Figure 4.0.4 xkcd “Git” (used with permission)

Notice that with a large project, there are many people working asynchronously and the potential for conflicts is very real as the mainline branch may advance rapidly from where a contributor initiated it. In the Sage project, reviews are not assigned, and are voluntary. A diligent contributor might regularly merge the master branch into their proposed branch, creating merge commits every time, with or without any necessary edits, which are then pushed to the public equivalent of GitHub. In this way, the contributor's proposed branch is always consistent with a relatively recent version of the definitive repository. Due to this, and to the public nature of the commits on a pull request, there will be many merge commits in such a repository. The network of commits begins to look less like a tree, and more resembles a slow, broad, meandering river with many branches forming, coming back together, splitting again, reforming,… Mathematicians refer to this network as a directed acyclic graph, which you may see described as “the DAG”. There is always an unambiguous path through the commits back to the original root commit.

If you have ever tried to collaborate on a writing project using email with attachments of traditional word-processing files (with or without “track changes”), then you may already be starting to appreciate how git's branches and remotes, along with GitHub's pull requests and notifications, can free contributors and overlords to collaborate efficiently and concentrate on content with very little procedural friction.