[Tex/LaTex] git LaTeX and branches workflow

best practicesgitrevision control

I'm getting more and more comfortable with git, and I'm learning how to use it with my LaTeX documents. However, I'm not at all a git wizard and thus I'm looking for further advices. One can find many hints and tips around (also in TeX.SE) but I would like to focus on the issue of branching in the context of a TeX document.

I currently I find the model of one-repository-one-document optimal for my needs. By a document lets consider an article for instance. Furthermore, let's assume that the repository is also pushing to a remote location which is shared with collaborators.

My question is: When and How should I branch and merge?

I came up with an idea what should be the workflow, but I'm not sure whether it is good enough, or did I miss something. See my answer.

Best Answer

I hesitate to say this, but I think you're doing it wrong; but you're close to what is, I think, needed.

The purpose of a branch is to separate an activity, not a structural component.

Thus, I would not have a branch for the "Introduction" file, but for the process "Develop the Introduction". This branch might include, for example, changes not only to Introduction.tex but also to Preamble.tex (\usepackage{todonotes}, maybe) and to Master.tex (\input{Introduction}, maybe).

That said, I suspect this is only useful if you're working as part of a team -- one doing the intro, one doing chapters 1-3, one doing chapters 4-8, for example.

As a solitary author, the way I work is this (I use git):

  • To a first approximation, one repo per document
  • A master branch which represents the life of the "public" document (also known as a "release" branch)
  • If you really need it, a development branch where you accumulate other branches before release
  • Ad-hoc branches for specific major items of work (eg "I'm moving from Komascript to Memoir")
  • But normal day-to-day evolution (eg just plodding along adding paragraphs) I do on the master branch or, if I need one, the development branch.
  • Frequent commits of bite-sized changes (eg It may be useful to separate the commits for the preamble separately
  • Try to obey the maxim "Don't commit a broken version" (I try but I don't always succeed)
  • Use tagging extensively to keep notes on what a given point in the graph means

Where I am building documents that go out to clients, I also do something strange:

  • Commit everything when the document is ready (but not the direct PDF)
  • After the commit, format the document anew and check it (this brings in my git commit reference for my dogfooded gitinfo)
  • Rename the PDF output to, say, client.2013-03-19.pdf, and move it to a folder called "archive", also somewhere in the repo
  • Stage and commit the date-specific PDF, and tag that commit appropriately.

This answer, I hope, may also be helpful: Automatic branching for versions and git

Related Question