$ git diff --color-words

followed by -S in the subsequent less pager.

Written by commandline (aka Thomas Gideon) at the request (behest?) of Cory Doctorow, Flahsbake was meant to address the problem of retaining an archival record of the production of digital texts. Cory Doctorow explains:

I was prompted to do this after discussions with several digital archivists who complained that, prior to the computerized era, writers produced a series complete drafts on the way to publications, complete with erasures, annotations, and so on. These are archival gold, since they illuminate the creative process in a way that often reveals the hidden stories behind the books we care about. By contrast, many writers produce only a single (or a few) digital files that are modified right up to publication time, without any real systematic records of the interim states between the first bit of composition and the final draft.

The problem is genuine, I have written about it before. Moreover, I agree that version control has a role to play in its solution. However, I have doubts about the utility of Flashbake. It’s simplicity is its virtue, but it is too simple. No commit messages? A record of ambient information is no real substitute. And Flahsbake’s users are supposed to be geeky enough to use a command line tool, but not geeky enough to master the following simplified workflow?:

$ git init
$ git add mynovel.txt
$ git commit -m "initial commit"
write write write
$ git commit -a -m "new commit message"

I am not sure I get it. Still, any version control is better than none. And maybe Flahsbake will function as a Git gateway technology. If you are interested in a less puzzled reaction to Flashbake see the Lifehacker article. But if you want to be a really nerdy writer, just use Git neat.

Here is a screenshot illustrating the clean and then dirty state of the development branch.

To install the GitHub bundle do the following:

$ sudo gem install git
$ cd ~/"Library/Application Support/TextMate/Bundles/"
$ git clone git://github.com/drnic/github-tmbundle.git "GitHub.tmbundle"
$ osascript -e 'tell app "TextMate" to reload bundles'

To install:

curl http://github.com/defunkt/gist/tree/master%2Fgist.rb?raw=true > gist &&
chmod 755 gist &&
sudo mv gist /usr/local/bin/gist

Some usage examples:

cat file.txt | gist
echo hi | gist
gist 1234 > something.txt

Using gist from within TextMate should now be trivial.

The best thing about Git is branching. However, there is a hiccup in pushing a branch to a remote repository that always makes me pause when doing it. So this post is nothing earth shattering. Just a brain dump in the hope that the procedure will become hardwired so that I don’t have to anxiously glance at a man page each time a create a remote branch.

Creating a branch in your local repository is easy enough:

$ git branch <local branch name>

And pushing the branch to the remote repository is easy as well:

$ git push origin <local branch name>

So what’s the problem? The problem is that your local branch isn’t automatically tracking the remote branch. You could edit the git config, but that is a hassle. There is an easier way, though. You can delete the local branch a create a new local branch from the remote one. Fortunately, this can be done in a line:

$ git branch -f <local branch name> origin/<remote branch name>

The key is the -f option—it forces the creation of a new branch even if one of that name already exists. And the second argument specifies the remote branch from which the local branch is created. Creating a new local branch in this way causes it to automatically track the remote branch, so that you can, for example, use git pull without further arguments.

$ cd my_git_repository
$ echo 'git push' > .git/hooks/post-commit
$ chmod 755 .git/hooks/post-commit

As I explained in an earlier post, it is useful to independently maintain any LaTeX preambles you may have in version control. Independently, that is, of your present LaTeX project. The rationale is simple. If you discover some heretofore overlooked need requiring a change to the preamble, it would be useful if this change were made available to any other LaTeX document that uses that preamble.

Here is how to do this with Git and Git submodules. (Something similar could be achieved with Subversion and Subversion externals.)

First, let’s create a Git repository for our LaTeX project:

~ $ mkdir myproject
~ $ cd !$
~/myproject $ touch mytex.tex
~/myproject $ git init
Initialized empty Git repository in /Users/markelikalderon/myproject/.git/
~/myproject $ git add .
~/myproject $ git commit -m "Initial commit"

mytex.tex is just an empty file so far. Here is the template LaTeX file that I am currently using:

%!TEX TS-program = xelatex 
%!TEX TS-options = -output-driver="xdvipdfmx -q -E"
%!TEX encoding = UTF-8 Unicode
%
%  my_title
%
%  Created by my_name on date.
%  Copyright (c) year. All rights reserved.
%

\documentclass[12pt]{article} 

% Definitions
\newcommand\mykeywords{} 
\newcommand\myauthor{} 
\newcommand\mytitle{}
\newcommand\mybib{}

\input{preamble/preamble}

%%% BEGIN DOCUMENT
\begin{document}

% Title Page
\maketitle
% \begin{abstract} % optional
% \end{abstract} 
\vskip 2em \hrule height 0.4pt \vskip 2em
% \epigraph{text of epigraph}{\textsc{author of epigraph}} % optional; make sure to uncomment \usepackage{epigraph}

% Layout Settings
\setlength{\parindent}{1em}

% Main Content



% Bibligography
\bibliographystyle{plainnat} 
\bibliography{\mybib} 

\end{document}

A couple of observations about this. First, I am assuming that the included preamble is called preamble.tex and is in a subdirectory called preamble. This is required since we will be keeping our preamble in a Git submodule, and submodules are always subdirectories of the superproject. Second, I have defined some commands, \mytitle, \myauthor, etc. Basically these are all the elements of the preamble that could change from one LaTeX project to another. (So, in the preamble, we have \title{\mytitle}.) This was done to generalize the preamble so it can remain constant from project to project. Also, with a template, it is useful to pull, in this way, all the bits you would need to fill in to the top of the document so that you don’t need to hunt through the code. Once you have added content to mytex.tex, you will, of course, need to commit these changes.

Next we want to push to a remote repository. I will assume that your remote repository is hosted by GitHub (they provide free accounts for publically availbale repositories). So create a repository, “myproject”, on GitHub and then:

~/myproject $ git remote add origin git@github.com:myname/myproject.com
~/myproject $ git push origin master

(where “myname” is your GitHub username).

Now for something mysterious, but it’s required for Git submodules to work. We are going to delete our local Git repository and clone the remote repository:

~/myproject $ cd ..
~ $ rm -rf myproject/
~ $ git clone git@github.com:myname/myproject.com

Now we are going to create a Git submodule. Your preamble, call it preamble.tex, needs to be in a git repository. For the sake of illustration, we will use the preamble I am hosting on GitHub:

% Packages
\usepackage{geometry} \geometry{a4paper} 
\usepackage{url}
\usepackage{pdfsync} 
\usepackage{txfonts}
\usepackage{color}
\definecolor{gray}{rgb}{0.459,0.438,0.471}
% \usepackage{setspace}
% \doublespace % Uncomment for doublespacing if necessary
% \usepackage{epigraph} % optional
 
% XeTeX
\usepackage[cm-default]{fontspec}
\usepackage{xltxtra,xunicode}
\defaultfontfeatures{Scale=MatchLowercase,Mapping=tex-text}
\setmainfont{Hoefler Text}
\setsansfont{Gill Sans}
\setmonofont{Inconsolata}
 
% Section Formatting
\usepackage[]{titlesec}
\titleformat{\section}[hang]{\fontsize{14}{14}\scshape}{\S{\thesection}}{.5em}{}{}
\titleformat{\subsection}[hang]{\fontsize{12}{12}\scshape}{\S{\thesubsection}}{.5em}{}{}
\titleformat{\subsubsection}[hang]{\fontsize{12}{12}\scshape}{\S{\thesubsubsection}}{.5em}{}{}
 
% Headers and Footers
\usepackage{fancyhdr}
\pagestyle{fancy}
\pagenumbering{arabic}
\lhead{\thepage}
\chead{}
\rhead{\itshape{\nouppercase{\leftmark}}}
 
% Bibliography
\usepackage[round]{natbib} 
 
% Title Information
\title{\mytitle} % For thanks comment this line and uncomment the line below
%\title{\mytitle\thanks{}}% 
\author{\myauthor} 
% \date{} % Leave blank for no date, comment out for most recent date
 
% PDF Stuff
\usepackage[plainpages=false, pdfpagelabels, bookmarksnumbered, backref, pdftitle={\mytitle}, pagebackref, pdfauthor={\myauthor}, pdfkeywords={\mykeywords}, xetex, dvipdfmx, colorlinks=true, citecolor=gray, linkcolor=gray, urlcolor=gray]{hyperref} 

Here is what we need to do to create the submodule:

~ $ cd myproject/
~/myproject $ git submodule add git://gist.github.com/835.git preamble
~/myproject $ git submodule init
~/myproject $ git submodule update

Now, if we want to make a change to our preamble and make it available to all our LaTeX projects that use that particular preamble, you need only commit these changes to the Git repository where your preamble lives.

For more information about git submodules, see this tutorial.

BryanL demos Gist: A Super Hot Pastebin from Bryan Liles on Vimeo.

In the spirit of sharing, I have posted my LaTeX preamble and associated files. Feel free to download or clone these files, or better yet, post your own!

It is useful to independently maintain any LaTeX preambles you may use. Suppose, for example, you discover some need and make a corresponding change to your preamble. You might want that change available to some of your other LaTeX documents. Next time I will explain how to do this with include statements and git submodules.

Daring Fireball, as ever, with the wry commentary:

It strikes me as an odd coincidence that two serious Subversion clients would debut at a time when many developers are starting to switch away from Subversion to distributed revision control systems such as Git and Mercurial.

Update Kieran posts about it here.

One useful thing that academics share, though less often than their research, is their bibliographies. LaTeX is predominant in academia, though not universally so. So many of these online bibliographies are BibTeX files. See Benj Hellie’s BibTeX file as an example.

Sometimes, these have been converted to HTML. Sometimes, as in Benj’s case, the author simply posts the text file (BibTeX is a flat file database kept in plain text). This has some limitations. One problem is that the author has to periodically export to HTML, and even if he is posting the text file, it still needs to be uploaded to the server. Unlikely that this is done after each change to the bibliography.

From the users side, there are problems too. Suppose I have downloaded Benj’s BibTeX file. Some time passes, and I want to take advantage of Benj’s hard work. Some of the entries I already have, some are new. Some of the new entries may overlap with entries that I have made independently. Manually merging this material can be a pain, even with diff tools.

All of this would be a lot easier if academics used distributed version control to share their bibliographies. Suppose the distributed version control system in question is Git. When an author makes a change to his bibliography, then all he need do is to commit the change and push to the remote repository:

$ git commit mybibtexfile.bib
$ git push

From the users side, to download the bibliography all he need do is clone the git repository:

$ git clone git@github.com:PhilGeek/bib.git

After that, fetching and merging new changes is easy as:

$ git pull

Well, I am putting my money where my mouth is and publishing my BibTeX file in an open Git repository hosted at GitHub—http://github.com/PhilGeek/bib/tree/master. To clone this repository:

$ git clone git@github.com:PhilGeek/bib.git

Even if you are not a Git user and are shy about adopting new technology, the file can be viewed and downloaded here.

There is not as much in it as there should be. Before becoming a plain text Geek, I kept my bibliography in EndNote. Unfortunately, my EndNote file, a proprietary binary format, became corrupted before I could convert it to BibTeX. Yet another cautionary tale speaking in favor of the Power of Plain Text.

1. Who am I?
2. Where am I?
3. Which branch of a Git repository am I on?

I wanted color. I wanted a multiline prompt. I wanted it all!

Actually it was pretty easy. Here it is, explanation to follow:

source ~/.git-completion.sh

export PS1='\[\e[0;32m\]\w\[\e[1;33m\]$(__git_ps1 "(%s)")\[\e[0m\]\n\u $ '

The first line loads .git-completion.sh a script distributed with Git that provides autocompletion for Git. Cool! But it also provides the function at work in:

$(__git_ps1 " (%s)")

This will display the branch currently checked out when you are in a Git repository.

The characters:

\[ \]

wrap nonprinting characters, in this case, the color codes:

\e[0;32m
\e[1;33m
\e[1;33m

Finally:

\w
\n
\u

gives you the name of the current directory, a new line, and your user name, respectively.

Well a picture is worth a thousand words:

I am now in the process of transitioning my work over to Git. One salient difference is that, with Subversion, I kept all my mission-critical text files in a single structured directory; Git, however, wants to find relationships among everything in the repository, so it is important to keep unrelated projects in different repositories. (Fortunately setting up Git repositories is a snap.) This is important to bear in mind when migrating from Subversion. If, like me, you maintained a single Subversion repository with separate subdirectories for each of your projects, you need to migrate each of these into separate Git repositories.

Here is how I began my migration.

I decided to start with my remind files:

$ mkdir -p /tmp/remind
$ cd !$
$ git-svn clone http://markelikalderon.com/svn/TheHub/Remind --no-metadata

The command:

git-svn clone

calls init, which creates a new Git repository, and fetch, which fetches the contents and history of the directory. git-svn clone takes the options of both init and fetch. One useful option is –no-metadata which strips out the no longer needed Subversion metadata.

Now I needed to configure my new Git repository. I began by creating a file and opening it in my text editor, TextMate:

$ touch ~/users.txt && mate ~/users.txt

I then added the following to users.txt:

kalderon PhilGeek <eli@markelikalderon.com>

‘kalderon’ being my Subversion user name and ‘PhilGeek’ being my Git user name. There should be one line each with this syntax for each of the users. Now I was ready to configure git:

% git config svn.authorsfile ~/users.txt

The final step is to clone this new Git repository to rid ourselves of any remaining svn cruft. I created a new GitHub project and then within the Git repository:

$ git remote add origin git@github.com:PhilGeek/remind.git
$ git push origin master

Finally, I cloned the remote repository into the directory where my remind files were to live locally and deleted the /tmp/remind directory.

Not too bad. But you might consider automating the process with a shell or ruby script, if this needs doing several times over.

RailsConf 2008 Git Talk by Scot Chacon Video from daniel wanja on Vimeo.

The slides of his talk are also available.

OpenInGitGui is an AppleScript droplet that allows you to open Git-Gui from the Finder. Install it in /Applications/Scripts (create the Scripts directory if it does not already exist), and drag the icon to the toolbar of your Finder. Select a folder containing your git repository and click the Git icon.

Sounds easy. It is. Though I had some troubles getting it to work. The droplet assumes that git-gui is in /usr/local/git/bin (where the git-osx-installer puts it). Installing git from source, however, places git-gui in /usr/local/bin. One could modify the AppleScript source but only the binary droplet is distributed, and a soft link results in an error. So make a hard link:

sudo mkdir -p /usr/local/git/bin/
cd /usr/local/bin/
sudo ln git-gui /usr/local/git/bin/

The only remaining annoyance is that the droplet opens a scratch terminal. This could be avoided with the appropriate AppleScript call. Again, it would be nice if the source and not just the binary was provided.