How to format source to take advantage of VCS?

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.


Per Loop Space's comment above, his tips at https://loopspace.mathforge.org/HowDidIDoThat/TeX/VCS/ are handy. Of particular use is dividing the layout code from the content (a good idea anyway) and managing line-wraps.

I tend toward long sentences with many dependent clauses, and my rewrites often combine or split these, so his advice about breaking lines at sentence boundaries is not quite enough for me; I’ve therefore gone beyond those tips, all the way to writing my prose as if it were blank verse: breaking lines at most punctuation points and at other phrase boundaries.

I would write the above paragraph/sentence thus:

I tend toward long sentences with many dependent clauses,
and my rewrites often combine or split these,
so his advice about breaking lines at sentence boundaries is not quite enough for me;
I’ve therefore gone beyond those tips,
all the way to writing my prose as if it were blank verse:
breaking lines at most punctuation points
and at other phrase boundaries.

(It’s somewhat exaggerated from my actual writing style, for illustration.)

ETA: I’ve just discovered a name for this technique: semantic linefeeds. Brandon Rhodes, in a blog post on the subject, quotes Brian Kernighan’s 1974 version of “UNIX for Beginners” [PDF]:

Hints for Preparing Documents

Most documents go through several versions (always more than you expected) before they are finally finished. Accordingly, you should do whatever possible to make the job of changing them easy.

First, when you do the purely mechanical operations of typing, type so subsequent editing will be easy. Start each sentence on a new line. Make lines short, and break lines at natural places, such as after commas and semicolons, rather than randomly. Since most people change documents by rewriting phrases and adding, deleting and rearranging sentences, these precautions simplify any editing you have to do later.