Two simple uses of Git for writing a thesis: reviewing & focussing

Git is a version control software, which helps software developers develop more software. Sounds complicated? It is! However, it has two features that you may find useful for writing (provided that happens in plain text files such as .txt, .md, .tex, etc.): commits and branches.

A project folder for a manuscript, written in LaTeX, and upgraded to a Git repo.
A project folder for a manuscript, written in LaTeX, and upgraded to a Git repo.

But first, a short introduction into Git’s basic concepts and terminology. The simplest way to install it is via the gratis GitHub Desktop apps. When you tell Git to assist you with a project, it settles itself into an invisible sub-folder.git (Surprise!). Thus, your project folder with the files and sub-folders that you see in your file manager is upgraded to a repository. In this repository, Git will now assist you by watching for changes in your files, while you can continue working on them normally. In other words: Git is a watchdog for your files, with your project folder as its range, and the .git sub-folder as its dog shed. Woof! Does it bite, or does it only want to play? We will find out…

Upgrading a project folder to a Git repository virtually splits it into two parts: history and staging area. The dog metaphor is breaking down here, but please bear with me. The history is simply the list of changes that were already committed, while the staging area is where Git shows you these changes.

Commits can simplify the reviewing process

Once you edited a file and saved the changes, Git visualizes these for you. Now, you can summarize logically connected changes (throughout one file, or many) as a commit and save that to the repository together with a commit message. As a service to your future self, or to whoever will review your work, you should concisely explain what the changes are or why they are relevant. While writing an academic manuscript, a commit could for example include the addition of an image file, plus its caption into the document text, plus changes to the text that refer to the new figure. Or, a simple proof-reading session.

History of a Git repository for a research article with several commits (left) and visualized changes within one of those (right).

This visualization of changes can be helpful for reviewing work. Either by yourself, for example by proof-reading yesterday’s changes in the morning, and then committing them. Or by your supervisor, co-author(s), etc. If they are even well versed in using Git themselves, it also becomes possible to author documents in a decentralized, collaborative manner.

Branches can help keeping the focus

In many software projects, it is necessary to keep a certain production status of the source code (e.g. that which underlies a publicly released version of that software) separate from the latest developments, experimental side projects, and/or code that fixes bugs. Git branches provide this tool for separating different contexts within a project. When a new branch is… Well, branched off, the same set of files in a project can be developed into a different direction. Like tree branches: having grown from a common root and stem, one branch may go straight up towards the light and produce many leaves, while another branch grows more horizontally and later carries the fruit. However, Git branches can be merged, thus integrating for example the code for a new software feature or a bug-fix into the code that will be released as the next version of the software.

In academic writing, this model can be adapted by for example keeping the content and the formatting of a LaTeX document separate from each other. This can help to concentrate on one or the other at the right times, instead of letting our monkey minds switch back and forth.

Focus on content
Switching branches swaps the respective files on that branch. This can help to focus on…
Focus on format
…different contexts, such as writing and formatting. Merging finalises the document.

Final words

Starting with Git is hindered by the fact that it’s optimized for software development. For text authors, there will be some hoops to jump through. If you are interested to learn more about using Git(Hub) in a scientific context, please see this audio slideshow specifically about lab journalling and this list of suggested reading.

What are your thought on Git for writing? Are your Git-ing your thesis? And if so, how are you Git-ing it right? And most importantly: What should we suggest to the developers of Git clients to make their software more useful for academic authors who want to track writing projects?

Beitrag von Katrin Leinweber | @kaleimai
#Algae #Bacteria biochemistry @unikonstanz. #FLOSS power user & bug-reporter. #R #Python & #Git noob. Hälfte des @KonSciencePodcasts. #OpenScience #TechSupport

4 Gedanken zu „Two simple uses of Git for writing a thesis: reviewing & focussing“

  1. Hi Katrin,

    you should not misuse git branches as different „views“ in your project. If you want to categorize files than put them into different folders.

    I doubt that there is much use for branches when writing a thesis because you have only one author and there aren’t different staging areas to run code like development, testing, production.

    On the other hand I’ve succesfully used git to merge the different contributions of a group work into a final latex document in one seminar. In that case there was still only one branch because the others didn’t know git (in a computer science course!). But if they’d have known git than every checkout on one of their laptops would effectively be a branch of the common project.

    I fully agree that everybody who works with any kind of text should learn git. It is incredibly useful to have a history.

    1. Hi Thomas,

      I used branches to organise myself, to experiment with LaTeX stuff like automating species formatting and to separate corrections by supervisors or colleagues from my own work. Thus, branches IMHO can be useful for individual authors, although of course they start to shine in team work. It also depends a lot on each person’s own mental model of the text. Me for example can’t write down long stretches of text down, after pre-formulating it all in my head. Branching helped me experiment and tie different strands of work together.

      there aren’t different staging areas to run code like development, testing, production

      Well… Initial draft, review & final version 😉 And LaTeX is kind of a build system as well, isn’t it?

      In any case, the ideas and experiences I outlined are very preliminary. Current source code versioning systems are not well-adapted for text writing. IMHO, useful improvements would be:

      – default word-by-work highlighting of changes
      – easy searching for keywords in deletions or additions
      – easy definition of comments or tasks lists to ignore

      I’ll keep on thinking about this, esp. on the GUI level 🙂 Do you have more ideas?

      1. – default word-by-work highlighting of changes
        I guess you know that git can do word diffs. If you need a shortcut for this you can define a git alias (see man git-config) for it. You can also use git attributes to call external programs to diff specific file types.
        – easy searching for keywords in deletions or additions
        Options -S or -G in man git-log.
        – easy definition of comments or tasks lists to ignore
        Don’t ignore them. Why not commit your comments or task lists? In the end they contain valuable information.
        Or put them into separate files.
        Or use some facility from your text editor to annotate lines without changing those files:

        1. With „easy“, I meant GUI elements 😉 Tower 2 and GitHub Desktop only have some of the discussed features. I know that it’s possible to cobble together all the necessary commands, extra tools etc., but that is close to intolerable for most scientists. Uneconomical as well, if you consider that they are mostly financed by the tax payers to do science and record their findings for posterity. Therefore, the writing environment should easily adapt to the needs of the writer. The other way around should be kept to a minimum.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.