blog · git · desktop · images · contact & privacy · gopher

Git collaboration for tiny projects, reloaded


Alright. My projects have moved. This means that some things work differently now. But how? How do you create a “pull request” now? How do you file a bug report? How do you check for open bug reports?

Note that I’m only talking about tiny projects. Larger projects may want to employ different techniques. And, of course, it’s just my subjective point of view. Feedback welcome, in case I’m missing something here – and/or if there are superior (and still simple) solutions to the following problems.

Browsing code and history

I’m currently using stagit to make my repositories browsable. It’s very lightweight, but it’s also lacking some features. For example, you cannot view the history of individual files. You also cannot view “raw” files – they are always annotated with line numbers and a header.

The answer is straightforward: Clone the repository to your machine.

Small projects usually have a small code base. Cloning them is a matter of seconds. Once you’ve done that, you can use whatever Git tool you like to further inspect the repo without any more network overhead.

Are you annoyed that this clutters your hard drive with lots and lots of repositories? Well, maybe it’s time for a shell alias like this:

    mkdir -p -- "$@" && cd -- "$@"

alias ttr='mt /tmp/r/$(date -Iseconds)'

All those “temporarily cloned repos” will be gone after the next reboot.

Bug reports and known issues

There is no traditional “bug tracker” anymore, but there might still be bugs in the code. If there are known bugs, a project will have a file called BUGS, which lists them. Simple as that.

If you want to inform me about a bug you’ve found, drop me an e-mail. Simple as that. I will then either fix that bug or add it to BUGS.

To be honest, I think that tracking bugs in a file inside the repository is a really good thing – for small to medium projects. It makes the repository more self-contained. As long as you keep the repo around, you’ll automatically keep a history of all bugs.

When using a traditional bug tracker, you’re inclined to write “see bug report #3” in your commit messages. I made that mistake. Now that I’ve lost access to my previous bug tracker, all those “see #3” links are now dead links. That sucks.

Of course, there is a time delay between you writing a bug report and me adding it to the BUGS file. I’m convinced that this won’t be a problem for my projects, since there is little traffic. Larger projects will probably want to set up a mailing list instead.

Sending patches

So, you’ve cloned a repo. Now what?

Not much has changed, actually. You create a new branch:

git checkout -b my-feature

And then you create your commits on that branch. Just as before.

vi foo.c
vi bar.c
git commit -av

You then have a bunch of options. The easiest one is to create patch files from your commits. You can do this with just one command:

$ git format-patch master

Then send me these files, for example via e-mail, and we can discuss your patches.

These are not plain patches, though. They include a small set of metadata that will be evaluated automatically by Git when I apply them via git am. Most importantly, your identity will be included; you will be properly listed in the final Git history as the author of those changes.

Of course, if you have your own server, you can simply host your cloned repo there and send me a link. Git is decentralized and I can fetch directly from your server.

Ugh, isn’t easier to use a Git hosting platform?

Yes and no.

Yes, because you may be used to it. You already know how it works on $PlatformA and $PlatformB. This makes your brain forget about all the nasty details and about the fact that “work” is involved.

No, because it’s naïve to think that way. For each and every project out there, you have to invest time. You have to get to know the project. You never just edit a file, click a few buttons in a web UI, and create a pull request. Well, you can do that, but your work is likely to be rejected. You have to check for the project’s code style (even though there are attempts at solving that problem), check for a contribution guide, understand that contribution guide, you have to understand the code’s license, maybe you are supposed to write test cases, and so on. Learning how to send patches is just a tiny part of that process.