17.3 Hacking: Using git with StumpWM

For quite a while now, StumpWM has been using the git version control system for development. If you’re using one of the official releases, you can get the bleeding-edge source code from the official git repository with a single command:

$ git clone git@github.com:stumpwm/stumpwm.git

After this, you’ll have a complete git repository, along with the complete revision history since the switch. Feel free to play around; git has some important features that actually make this safe!

Before we get to that stuff, though, you’re going to want to tell git about yourself so that your information is included in your commits and patches. The very minimum you’re going to want to do is:

$ git config --global user.name "Anne N. O'Nymous"
$ git config --global user.email "anonymous@foo.org"

Be sure to check out the manual for git-config–there are several options you might want to set, such as enabling colorized output or changing the editor and pager you use when making commits and viewing logs.

For the sake of argument, let’s say you want to make some major changes to both ‘user.lisp’ and ‘core.lisp’, add a file called ‘DANGEROUS_EXPERIMENT_DO_NOT_USE_OR_ELSE.lisp’, and remove the manual because you’re too 1337 for such things. However, you don’t want to break your entire StumpWM setup and start over. Thankfully, you don’t have to. Before you get started, issue this command from the StumpWM source directory:

$ git checkout -b experimental

You should now find yourself in a new branch, called experimental. To confirm this, type git branch; there should be an asterisk next to the branch you’re currently viewing. At any time, you can type git checkout master to return to your master branch, and at any time you can have as many branches of the project as you like. If you want to create a new branch based not on the master branch but on your experimental branch, for example, you’d type:

$ git checkout -b new-experiment experimental

This will place you in a newly-created branch called “new-experiment” which should be identical to your experimental branch as of the last commit (more on that soon). If you’re actually typing out the directions, switch back to your old experimental branch like so:

$ git checkout experimental

Anyway, now that you have a new branch, create that new file with the long name, which we’ll just call ‘danger.lisp’ for brevity. Make whatever changes you want to it, and when you’re done, tell git about your new file.

$ git add dangerous.lisp

Now, let’s pretend you’re done making changes. Tell git you’re done for now:

$ git commit

This will open up a prompt in your editor of choice for you to describe your changes. Try to keep the first line short, and then add more explanation underneath (for an example, run the command git log and take a look at some of the longer commit explanations). Save that file and then do this:

$ git checkout master
$ ls

Then look for your new file. It’s not there! That’s because you’ve done all of your work in another branch, which git is currently hiding from you so that you can “check out” the branch called “master.” All is as it should be—your master repository is still safe.

$ git checkout experimental

Now, delete ‘manual.lisp’ and ‘stumpwm.texi’. That’s right. Wipe them off the face of the Earth, or at least off the hard drive of your computer. When you’re done, you don’t have to tell git you’ve deleted them; it’ll figure it out on its own (though things may not compile properly unless you edit ‘Makefile.in’ and ‘stumpwm.asd’. Anyway, go ahead and edit ‘core.lisp’ and ‘user.lisp’. Really break ’em. Run free! When you’re done, do another commit, as above, and give it a stupid title like “lolz i b0rked stUmpwm guys wTF!?!?!!111!” Now try to compile. Just try. It won’t work. If it does, you’re some kind of savant or something. Keep up the good work. If you’ve actually managed to break StumpWM like you were supposed to, never fear! You have two options at this point.

One is to go back to the master branch (with another git checkout) and just delete your experimental branch, like so:

$ git branch -D

The “-D” means to force a delete, even if the changes you’ve made aren’t available elsewhere. A “-d” means to delete the branch if and only if you’ve merged the changes in elsewhere.

The other option is to create patches for each of your commits so far, delete the branch, and then apply any working/wanted patches in a new branch. Create your patches (after committing) like so:

$ git format-patch -o patches origin

(Before doing that you can review your changes with git log origin..)

You can also use the format-patch command to create a patch of working code to send in to the mailing list.

A developer might ask you to try out something they’re working on. To fetch their master branch, you’d do this:

$ git remote add -f -m master -t master foo git://bar.org/~foo/stumpwm

Here, “foo” is the shorthand name you’ll use to refer to that repository in the future. To checkout a local copy of that repository, you’d then do

$ git checkout --track -b foo-master foo/master

Later you could use git pull foo to update while looking at that branch (and note that git pull with no arguments, in the master branch, will update your StumpWM from the official repository).

Finally, if you want to move your experimental changes into your master branch, you’d checkout your master branch and run:

$ git merge experimental

If there are file conflicts, git diff will show you where they are; you have to fix them by hand. When you’re done, do another

$ git commit -a

to finalize the changes to your master branch. You can then delete your experimental branch. Alternately, you can wait until your changes (assuming you sent them in) make it into the official repository before deleting your experimental branch.

This document was generated on January 28, 2024 using texi2html 1.82.