Hacking

When complete this page should serve as a guide to hacking on the Bitrig ports tree. Since we use github for ports, we can start with a few tips there.

Normally, one checks out the ports tree in /usr. You will need a lot of space there to build ports so make sure it is on a large partition (I have 40G for /usr on my laptop but if you only plan on working on a few ports and are careful about cleaning up you can get away with less. You should probably clone from the github repo and then add your own fork as a seperate remote if you plan to make changes. If you just want to build existing things then you don't have to fork and add the remote.

cd /usr/
git clone git@github.com:bitrig/bitrig-ports.git ports
cd ports
git remote add github git@github.com:USERNAME/bitrig-ports.git

You should add your user to the group wsrc and then change permissions on the repo you checked out so you can edit it.

sudo usermod -G wsrc USERNAME
sudo chgrp -R wsrc /usr/ports
sudo find /usr/ports -type d -exec chmod g+w {} \;

In general it is best to start by forking the repo on github, and then doing you work on a branch:

 git checkout -b YOURNAME_WHAT_YOU_ARE_DOING.

When ready you can then do a Pull Reguest through the github webpage for us to review. If you do not use github we can always take patches by email (probably best to find a specific person to mail that to rather than the mailing list) although github is probably easiest for everyone.

One of our goals with git is to keep a nice, clean history. Obviously with so many ports the overall history will be less than simple to read but if you limit it to a single port:

git log CATEGORY/SOMEPORT

it should make some sense.

To help with this we will usually squash commits before they go in if there are multiple commits for a given feature or change. On the other hand, if you are changing multiple ports, please keep your commits seperate (unless you are doing the same thing to many ports such as marking serveral ports broken). When in doubt, just ask us.

When you are hacking on a branch it is very possible that new commits will be done on master before you get in. In this case it is usually helpful to rebase you branch against master so it is all caught up.

Git rebase rewrites your branch by taking each commit of yours and putting it on top of the other branch one at a time. This way it is as if you started working on the updated branch rather than your old branch.

In the example below I am assuming origin points to the github.com/bitrig/bitrig-ports and YOURGITHUB points to you fork. If you have any uncommitted changes it is important to run git stash first.

git stash
git checkout master
git pull origin master
git checkout YOURBRANCH
git rebase -i master

That will open up the list of new commits on your branch in your $EDITOR. If you aren't squashing or throwing any away, just save and quite the editor.

Then it will open a list of commits messages that you can edit. Again, if you aren't changing anything, just save and quit.

It will now replay your commits one at a time onto master. You will have to fix any merge errors here.

If git stops on one of your commits with conflicts, find the file or files with the problem (it will usually both modifed)

git status

Edit the file or files until they are correct then add it when done:

$EDITOR FILE
git add FILE

Repeat this for each file with a conflict. When done.

git rebase --continue

When it gets through all of them, you are done. Now push your branch. Because your branch has a changed history you will have to force push your branch (this is the ONLY time force pushing is a good idea).

git push YOURGITHUB YOURBRANCH --force

And now you are ready for more hacking or to do the PR.