The Gist

You can spot the imposter because he’s wearing glasses:

Apparently, LASIK brings out your inner Cubs fan.

Word-a-Day

For anybody who missed the massively cross-posted announcement, we’re in the middle of the Word-a-Day program on gnome-doc-list. The terminology recommendations in our Style Guide are seriously out of date, so we’re doing a complete refresh. To get full community involvement, I’m sending one(-ish) word each(-ish) day to gnome-doc-list for discussion. If you like words as much as I do, join the fun.

Silke Out, Shaun Sad

So Silke’s off in San Francisco for the SIOP conference. I, apparently, am not capable of figuring out how to sleep properly on my own. I fell asleep on the couch last night watching Colbert and woke up at 7:30. Waking up on the couch when it’s already light outside is strange.

On the positive side, I’m using this as a chance to have some old friends in from out of town. Although so far, Bill’s the only out-of-towner confirmed, so it’ll mostly be local friends.

I Love Cedar

Yesterday I bought a bunch of cedar and starting building a potting bench for my greenhouse/shed. What happens when you take half an inch off of nine 6′ 2x4s in the planar? You get a huge pile of wonderfully aromatic cedar shavings. I don’t know what I’m going to do with the shavings yet, but they sure smell nice.

People who hang out on #gnome-hackers will have already heard me talking about Pulse.  No, not the awesome audio server.  That’s PulseAudio.  Pulse is my project tracker.  A crawler periodically rumages through things that are relevant to your software project and sticks things in a database.  Then we can see nice summary pages like this page for the Gnome 2.22 desktop.

At first glance, it might appear I’m just trying to clone CIA or Ohloh.  While I’ve taken some ideas from each, Pulse serves a different purpose.  You might compare it to Launchpad, although Launchpad is an active project manager, whereas Pulse is a passive project tracker.  marnanel described it as “Facebook for Gnome”.  No, I am not going to add poke.

Pulse grew out of the documentation team’s need for an automated documentation tracker.  We really need to be able to see, at a glance, what documents there are in a given release set.  We need to see who’s working on what and how far along those documents are.  And we need to see what modules should have documentation, but don’t.  My obsessive abstractionitis, however, led me to create a system that tracks everything.

If anybody’s interested in playing with it, the code is in git: http://www.gnome.org/~shaunm/git/pulse.git .  Here’s a rundown of things abrewing:

• If you go to any module’s page, you can click the shortened comment of a commit for a popup with the full comment.  If this happens to be any module on svn.gnome.org, you’ll also see a yellow bar that lets you get diffs and info on svn.gnome.org/viewvc.  I’ve special-cased svn.gnome.org here, which I don’t like doing.  A general-purpose “find the webview for this SCM server” would be great.
• I want to track mailing lists.  I think I’d rather avoid subscribing Pulse to any mailing lists, and instead just periodically poll each list’s web archives.  That much is pretty straight-forward code.  What I need to figure out is how to find the mailing lists associated with any given module or team, and how to find the web archives associated with any given mailing list address.  The less I have to special-case anything, the better.
• I really want to track bug databases.  For any given module, I want to know what bug databases to use.  Notice the plural.  I would love to show stuff from distros’ downstream bug systems.  For any given bugzilla product, I want to know its components, and the default assignees and QA contacts for those components.  This is, by the way, incredibly useful for the documentation team, as we could quickly see what belongs to gnome-user-docs-maint@gnome.bugs.
• If we could semi-reliably find FOAF files for people, we could show a lot more information about them.

Basically, Pulse should be useful, not just a collection of random interesting facts.  (Random interesting facts are great too, but only in the context of an otherwise useful system.)  If you’re a maintainer, I want the Pulse page for your module to be useful to you.  If you’re an occasional contributor, I want Pulse to make it easier for you to contribute.  If you’re a documentation writer, I want Pulse to help you find documentation to work on.  et cetera, et cetera.

Comments, suggestions, criticisms, flames, and praises welcome.

Not long ago, somebody wrote a blog entry about recovering files from a partition. If anybody knows who that person was, please let me know in the comments.

Here’s what happened: Silke and I had a friend take a video of our latest Rueda performance on Saturday using our shiny new video camera. The camera just mounts USB mass storage. So I selected the videos in Nautilus, dragged them to a local folder, and deleted them. I know, dumb, right? The video of our performance is nowhere to be found, and I have no idea why. I know the video was actually taken, because we watched it on the camera right after the performance.

The first thing I did when I realized my mistake was dd the device to a local file. I’ve tried PhotoRec and Foremost. Foremost did jack for me. PhotoRec managed to recover some other videos I’d deleted, but not the one I want. Any other suggestions would be appreciated.

Update, this is the blog post I was thinking of. Thanks to Tobias who pointed me to Jakub’s blog which had a comment with this link.

We’ll be having a long-overdue Mallard planning meeting this Sunday, 2000-02-03, at 16:00 UTC. That’s 10 in the morning for us Midwesters, and 17:00 for most of Europe. As usual, the meeting will take place over IRC in the #docs channel on irc.gnome.org. See our meeting page for the agenda.

Silke and I are involved in a Rueda group that put on a performance last weekend. The performance was choreographed (rather than the moves being called out, as normally happens). Last-minute planning made for hectic rehearsals, especially for me and Silke, since we ditched the group the weekend before for a weekend of West Coast Swing. But I think it turned out well in the end.

So here’s our Rueda performance on YouTube.

That video had cruft at the beginning and end I had to cut out. It seems the Gnome camp hasn’t yet produced good video editing software, so I did what I always do when I need to get something done: I pulled out my trusty friend Python. Together with GStreamer, doing basic transformations to the video wasn’t that hard, once I wrapped my head around it all.

This got me thinking that, with GStreamer, somebody could pretty easily make the equivalent of ImageMagick’s convert for audio and video files. A really simple command line tool that can slice time segments, crop regions of video, adjust brigthness/contrast/etc, adjust audio stuff, scale and resize, and so on. While not as awesome as a full-blown GUI video editor, this kind of tool would still be incredibly useful. And it would probably be a weekend project for somebody who knows GStreamer well. Any takers?

In an attempt to mitigate the RSI in my right wrist, I’m teaching myself to mouse left-handed. It’s going reasonably well, but I’m still faster and more accurate with my right hand. I’d really like the option of using a right-handed mouse when I’m doing something very important, such as playing a game of Mines.

Of course, I can easily attach two USB mice to my computer, and they both work. The problem is that the mouse preferences apply to all mice. I need a way to set mouse properties per-mouse. (Incidentally, I’ve wanted this feature before to set the sensitivity differently for my laptop’s touchpad from an external mouse.)

I’ll buy a beer for the first person with a solution. I’ll buy two beers for the first person to say “Hey, this should just be easy” and change the mouse preferences capplet to make the solution all clicky-clicky.

In my last post, I discussed the basics of using git with a central repository, doing the sorts of things that we do in Gnome. There were some very helpful comments, and I’d like to share some of that information for the benefit of everybody else.

Branching

My instructions for creating and working on a local branch went like this:

git branch whizbang-feature master
git checkout whizbang-feature

Behdad pointed out that you can use the -b argument with git checkout to create a branch and check it out, all in one command. So those two commands become

git checkout -b whizbang-feature master

Of course, as with git branch, if you omit the last argument, it defaults to branching from whatever you currently have checked out.

Updating

My instructions for getting updates from the server were

git pull origin

Behdad, Marko, and daniel all pointed out that this isn’t optimal. You very likely have changes in your local repository. What you want is to get the remote changes and merge your local changes on top, as if they were developed from the now-current remote repository all along.

git fetch

This fetches the changes from the remote repository and puts them in your local repository. They are not merged in with your local checkout, just the local repository that’s sitting in .git.

It should be pointed out that git pull is basically just a shortcut for git fetch && git merge. But git merge attempts to merge the two development histories (remote updates and local changes) together, rather than just sticking your local changes on the end. So instead of git merge, we’ll call

git rebase origin/master

The git-rebase(1) man page has a nice ASCII diagram to help you visualize what’s happening.

This is not a “let’s use git” post. This is a “here’s how we’d use git, if we did” post. With all the recent git talk, I decided I’d try learning it with one of my on-again-off-again projects, Pulse. Caveat: I am not an SCM geek. I don’t enjoy learning SCM systems for the fun of it. I just want to be sure that whatever we use fits our needs. (Further disclaimer: I actually like CVS more than I like SVN. Infer what you will from that.)

If you go looking for documentation on git, you’ll find information on how to set up your own repository, how to clone other people’s repositories, how to make your own little personal branches (and why you should), and how to push/pull/merge. What they generally don’t discuss is how to work with a central repository.

So here’s my day-to-day Gnome SCM activities, translated into git. These instructions assume that Yelp is stored in the mythical git repository ssh://git.gnome.org/yelp.git. If any git people spot something braindead, point it out.

Checking Out

git clone ssh://git.gnome.org/yelp.git

This will clone the entire Yelp repository into a new directory called yelp. Initially, that directory will be working on a local branch called master, which is branched from the master branch on the server. The alias origin is created to refer to the repository on the server.

To get updates from the remote repository (the analog to cvs|svn update), run

git pull origin

If you’re using lots of remote branches, you may need to run somethinng like

git pull origin master

Committing

So you’ve made some changes to some files. To see what’s been changed, run

git diff

Without any options, this shows the differences between the data on your file system and the data in the index. The index is basically all those local changes that you’ve told git you want to commit. Let’s say you’ve modified yelp-document.[ch]. To add your changes to the index, run

git add src/yelp-document.c src/yelp-document.h

Now git diff shows no changes, because all the changes are in the index. But they haven’t actually been committed to the repository yet. To see the differences between the index and the repository, run

git diff --cached

To commit these changes, run

git commit

If you’re thinking there must be a way to skip the git add step, you’re right.

git commit -a

This will find all the differences between your local files and the repository, add them to the index, and commit them. Of course, you still need to use git add to add new files.

Committing Remotely

All you’ve done in the steps above is commit to your local repository. Git people will tell you you should do this early and often, and then push your local changes when a suitable chunk of work has been done. So to commit your work to the central repository, there’s one more step to take.

git push origin

Remember that git clone set up origin as an alias for the remote repository you cloned. Without any extra options, this will merge the changes on your local branch (master) to the branch of the same name on the remote repository.

Branching

Git people will tell you to create a new local branch for any set of changes you’re working on. If you’re working on fixing some bug, make a branch for that bug fix. If you’re implementing some whizbang feature, make another branch for that. You can easily switch between these branches. To create a new branch, run

git branch whizbang-feature

This creates a local branch, branched from whatever you currently have checked out. If you currently have the stupid-bug branch checked out, and you want whizbang-feature to branch from master instead, run

git branch whizbang-feature master

This just creates the branch. Your local copy is still a checkout of whatever it was before you called git branch. To start working on the new branch, you’ll want to check it out from your local repository:

git checkout whizbang-feature

You can always see your local branches by running

git branch

Remote Branches

If you check out Yelp and run git branch, you’ll only see your own local branch, master. But Yelp has lots of branches in the central repository. We make them for every stable release series. So where are they?

git branch -r

The -r argument causes git to show the branches on the remote repository you cloned from. You refer to the remote branches by prefixing them with origin/, which you’ll recall is the alias for the remote repository. If you want to look at the stable gnome-2-18 branch, you could run

git checkout origin/gnome-2-20

But if you want to make changes, you should really create your own local branch instead.

git branch gnome-2-20 origin/gnome-2-20

Now you can commit your changes to your local branch, then git push them to the remote branch.

Creating Remote Branches

In Gnome, we create branches for each stable release series. As a maintainer, you need to create branches in the central repository. So you can create a branch like this

git branch gnome-2-20

But that branch is just in your local repository. To push the branch to the central repository, run

git push origin gnome-2-20

Now other users will see this branch when they run git branch -r.

Tagging
In Gnome, we tag our central repository for releases. So if you release Yelp 2.20.0, you need to create the tag YELP_2_20_0. Creating a tag in your local repository is simple:

git tag YELP_2_20_0

But we need this tag to be in the central repository. To do this, we git push the tag up:

git push origin tag YELP_2_20_0

When you clone a repository, you get all its tags. To see all the tags in the repository, run

git tag -l

And So On

Obviously, there’s a lot more to learn to make really effective use of git. But most of that information is readily available elsewhere. I mosty wanted to address how to work with (and maintain) a central repository, because most git documentation doesn’t. Comments welcome.

This Sunday, we will be having two documentaton team meetings: one for our writers, and one for our hackers. The meeting will take place on IRC, in the #docs channel on irc.gnome.org. The writers meeting will be at 17:00 UTC, and the hackers meeting will be at 18:00 UTC. See the email announcement and the online agenda.