Quick Instructions

To get the latest changes, from inside the downloaded git repository, run:

git pull

Note however that this only does what you expect if you haven't made any changes. If you have, it will attempt to merge your changes which may or may not be what you want; see "Local Changes" below.

Branches

There are two main branches in the Openbox git repositories: work and master. The difference is that our work branches can have testing stuff and be rebased (which means git will get confused if you try to pull from them). Once we are pretty sure something will at least not blow up, it will be put on the master branch and we try not to rebase that unless really needed.

By default you will get the master branch, hence the name. If you want the work branch, the first time you will need to run:

git checkout --track -b work origin/work

or if you have a recent git (somewhere in 1.6.x) you can just do:

git checkout -t origin/work

You can now switch between them with git checkout master and git checkout work.

If you want the very latest changes, first decide if you want master or work. For master, you can usually just run git pull, but if you're on work, you probably want to run something like:

git fetch; git reset --hard origin/work

Note though that this will delete all local changes to checked out files and also any commits you've made on the current branch. If you do have commits, you can try git pull --rebase but no guarantees. If something goes wrong, anything you've committed is actually still available, read the git-reflog man page for details. Uncommitted changes will be gone after a reset --hard though.

Local Changes

Unlike CVS and Subversion, git lets you have local changes while still tracking upstream development, in a nut shell, make your changes and run:

git commit -a -m "informative message"

It's usually a good idea to keep your changes in a separate branch. You can do this in a couple of ways, the easiest way is to run:

git checkout -b my-branch master

and then commit all your changes to that branch.

Conflicting Changes

If you hang on to your changes for a long time, it's likely that we will make commits that conflict with yours. There are two ways to deal with this, you can either git-merge our branch and resolve the differences, but the better way is to use git-rebase. This command will take your commits and apply them to the tip (the latest version) of the specified branch, pausing after each commit that conflicts. This usually makes it easier to resolve the conflicts and also gives a nicer history. Using git-rebase is a bit complicated, so read the man page.

If you just want to test that your changes work with the latest version of Openbox, you can merge master and then later use git reset --hard HEAD^ to revert the merge. However, I recommend first doing a git checkout -b my-temp, since running git reset twice will continue reverting real commits, so it's easy to mess up. If you're doing all the temp merging on a separate branch you don't have to worry about that.

Contributing Code

GitHub workflow

If you'd like to use the GitHub workflow, then make a fork of the Openbox git repo above via GitHub, and send pull requests from your branch with your code changes. GitHub.com has documentation describing this process.

Bugzilla workflow

You've coded an exciting feature and now you want to send a diff, how to do it? git diff you might guess, and while that will produce a diff you can send, git format-patch is a bit nicer as it will automatically give you a patch file per commit that you want to send, with the commit message in each file.

In the simple case where you just want to send off the top commit from your repo, do:

git format-patch -1

If you have a bunch of patches and you have git 1.7 you can do:

git format-patch @{u}

and it will figure out the correct branch to consider "upstream" and spit out a bunch of patch files. If you don't, you have to give the range manually, but it will almost always be:

git format-patch origin/master

Once you have your patch(es), open a bug in the bugzilla as instructed here.

Another option is to set up your own public repo and simply tell us where to pull your changes from, look at the git-daemon man page for details. This is not really preferred usually though, and you'll probably need to be patient and hang around in the IRC channel for a while.

Low Bandwidth Option

If your internet connection is very slow (the full git repo is currently around 8.5MB) and you just want the very latest version without any history, you can run:

This will give you only the current and preceding commit from each branch, but you can't do much more with your repo than compile the code. Merging as described above will only work if you use a depth high enough to include the point where the backport branch separated from master. See the git-clone and git-fetch man pages for further details.

You can also download a tarball of any revision via gitweb. Click "tree" next to a branch name at the bottom, then "snapshot" at the top of the new page.

Alternate repos

Due to the distributed nature of git, you can choose to pull from various upstream locations (see the git-remote man page for details on how to use several remotes).

The astute git user will notice that there are some variations in branches offered among these, for example dana has a libs branch that separates out some common wm code in a library, and mikachu has a mikabox branch which is just some crazy stuff.

Further reading

On the git homepage there are many great tutorials and all the man pages are available for browsing as well.