wikish/ git-writing

Git For Writers

I will gladly write a blog post on this subject, but I thought that: I'd put some notes here and see if we can collect some greater notes on the subject here. I'm tempted to put this in the Cyborg Institute wiki, but whatevs.

The thing that's so awesome about git, is that it basically does its thing all by itself without a lot of interference from you, and it lets you do your own thing, in whatever way you can and want. And git doesn't really care. As a result "git for writers" is really just "writing in non-binary formats with a file system that has a notion of history and can support non linear development." And the truth is that the history and the non-linear development are only tangentially/occasionally interesting/relevant.

As for the practicalities, it seems that there are a few areas that might be of interest:

Commit Style

(e.g. do you commit early and often because you can? do you set up some sort of cronjob to auto-commit regularly. do you only commit certain kinds of changes?)

Advanced Feature Usage

(e.g. do you use branches much, and for what? Stashes? Rebasing?)

  • I think there's a lot of fun to be had with collaborative authoring here. Having different plot twists being developed in topic branches and merged into a mainline might be a bit of a different authorial experience to what many are used to! --alaricsp

    • This idea, comes out a bunch, I feel, and I think it's not nearly as practical as people want it to be. I've written a bit about this and it strikes me that while it would be really nice to be able to have a bunch of people working on different aspects of the same text and then merge them all together in the end, this isn't terribly practical.

    Pragmatically, at least from the writing perspective there are some problems here. Generally plot threads aren't isolated from other plot threads. If we have two story lines in a novel, that follow characters "Sally" and "Thomas," the chances of being able to alter Sally's story without altering Thomas' isn't terribly good. Editing, of course can very easily happen in branches in a very nifty and non-linear fashion, but that's much less sexy.

    There's also a technical hurdle here: in order for the merges to work seamlessly, one has to have fairly short lines with hard returns, which isn't how we tend to work these days. Not only do you have to work in plain text files, but you have to be neurotic about how the files are organized and managed. And if you commit after reflowing a paragraph, it's likely that git won't be able to merge terribly well.

    Having said that, it is a pretty nifty idea, and git brings us much closer to having the technology to support this kind of text-making practice, but we're not there yet. For sure. --tychoish

Tooling

(e.g. what tools you use with git to get the job done?)

Not just the text editors and scripts that you use to deal with the text, as ?WritingInPlainText is a whole 'nother can of worms, but the tools that you use to interact with git. Flashbake. Your own scripts. etc.

  • A text editor. Do people use git for non-diff-friendly formats like MS Word? I know git has some ability to put custom diff/patch implementations in to allow for merging changes in Word documents, and display of readable diffs in gitk; has anyone actually done this? If not, do you write in plain text, ?MarkDown, HTML, TeX? --alaricsp

  • I write in emacs (of course,) but other text editors suffice. My default major mode, for whatever it's work is markdown, though I use ?ReStructured Text for work, because that decision was made before I came on-board. I also have files in org-mode, which is like neither RST nor markdown, and those are all in git and have writing.

    I mostly interact with git via the command line but have tinkered with the magit mode and quite like it. Some day I'll try to learn a bit more of vc-git, but the fact that the command line interface works for me means that I don't really use other interfaces. I used to have a personal git-web setup, but then I moved servers and only set up a public git-web (currently inaccessible for some reason I can't figure out) and haven't really missed the alternate interface. --tychoish

Project Organization

(e.g. how do you organize your files within git?)

Publication Hosting

(e.g. where does git push to, if anywhere?)

  • GitHub's pages system is an easy way to get content from a git repo onto the Web; you just push to a gh-pages branch on your project repo. This is a fairly effortless way of letting folks see your work-in-progress. --alaricsp

  • ikiwiki, which is a straightforward wiki compiler that uses git (or any source control mechanism,) and has some hooks to make the whole publication thing work a bit better. This is probably my old standby, but the wiki format often makes project organization much more difficult. --tychoish

I'll try and explain how I work in my blog post, and fill out this page as I collect my thoughts on the subject, but I think it might be helpful to hear how other writers/non-coders use git. --tychoish