[Tex/LaTex] How to format source to take advantage of VCS

best practicesrevision control

Building on What are good working practices for VCS with LaTeX documents?, are there best practices for formatting (La)TeX source files to take advantage of version-control systems?

I keep my résumé in LaTeX form in a git repository, for example, saving various job-offer–specific tweaks in branches. When I update the formatting or basic information on the main branch, I try to rebase the tweaked branches to fit, but the operation tends not to apply cleanly. I don’t have this problem with my C code, so I’m wondering how I might do better with LaTeX source.

Best Answer

This isn't an optimistic answer, nor, probably, a very good one. It is based on my experience using git, and the accidents I had while trying to use git to manage different configurations within a number of projects.

Why I think rebase isn't the answer

I believe that the philosophy of version control systems is directed at linear development with asynchronous side-events. What I mean by this is that the flow is always forwards, never sideways. When branches are created, their use, by design, is to provide a semi-independent development stream with one of three destinies:

  1. It is merged back into a single mainline development stream

  2. It stops. A good example of this might be the 'archive' branch from Loop Space's excellent description, or a product release.

  3. In some cases, it stops, but fixes are added in from time to time. This is more likely, I think, with post-release bug fixes than it is with archived documents, which have a very different life cycle and are used, if at all, in a very different way.

Rebase is a form of merge; both are designed to, in some sense, bring the development streams 'back together' by including all the history, and this is not what you want when the development streams are, in fact, diverging configurations. Models 1 and 2 don't work for handling configurations, and, on the three or four times I've tried to do this, I've always ended up having to restore my complete project and repo from backup. I accept that this could be seen as careless -- I'm still learning git the hard way!

Why I think cherry-picking is better than rebase, but still not the answer

Another option I've tried, and am still trying, is to use cherry-picking. Here you can select individual commits (as patches, conceptually) and apply them to the head of some other branch. This works a bit better, but it is essential that you separate your commits which change a given configuration from those which apply to many or all configurations. (That's probably obvious, but it took me a few failures to learn.)

I'm currently using this method to manage a rather complex proposal where I am (one day to be) a subcontractor. The proposal has two configurations: one for the prime contractor, and one for the end client, with some bits just omitted and some with minor changes of wording. Managing changes this way is taking much more work than I had hoped.

What I plan to do for all my new projects that need this

In the end, I've come to the conclusion that this isn't the best approach, either. I now firmly believe that the different configurations should be handled in a single branch by having relatively small and simple top-level files, one for each configuration, inputting one or more master files which are configured through the use of the verbatim 'comments' environment, the comments package, or my own, rather more limited, tagging package (though even vulture chicks are pretty in the eyes of their mum). My answer to Multilingual document is a very simple example.

Under this regime, you can archive or provide other fallback reference points through the use of tags or branches (whichever you prefer). But all of your configurations are carried along together, not separately, and I think this makes the whole thing (both version and configuration control) a lot easier.

Closing ideas

One positive thing I can recommend here for git users: Syntevo's Smartgit. It's index editor allows you to break changes up into smaller bits for multiple commits to allow clean cherry-picking, and it's stashing interface is clean and easy to use.

As I said at the start, this probably isn't the best answer; I'm working at the limits of my mental capacity here. So I'd welcome comments, criticism, and improvements from my technical superiors.

Related Question