Working with the contrib repository

Note: this is a practical description intended for contrib maintainers; for information on how to join the project see the HowToContribute and ContribRules pages.

Generic git documentation

Some familiarity with git is recommended: Here you can find the manual pages and some nice tutorial.

The contrib-test repository

There's a repository called contrib-test.git that you can use for your very first steps with git. It's not connected to the real contrib.git repository, so you cannot break anything when working with it.

Before starting

To tell git who you are and to define some useful defaults, set up ~/.gitconfig like this:

[user]
    email = my@myhost.org
    name = Your RealName
[push]
    default = current

Now configure ssh for access at crux.nu: edit ~/.ssh/config to tell git where to find the public key you will use for committing changes:

Host crux.nu
    HostName crux.nu
    Port 2222
    PreferredAuthentications publickey
    IdentityFile ~/.ssh/my_contrib_id
    User git
    ForwardX11 no

Getting the repository

$ git clone ssh://git@crux.nu/ports/contrib.git contrib

Configuring branches

The previous command should clone the latest available contrib repository into a "contrib" directory. Now run the following commands to configure branches:

$ git branch 3.6 origin/3.6
$ git branch 3.7 origin/3.7

This tells git to grab the necessary branches.
Note that the new contrib repository has one branch for each CRUX version, thus giving the possibility to work on a future release and backport updates to a previous one, much like the core and opt collections.
When development for a new CRUX version has started, you can simply add this new branch to your local repository, e.g.:

$ git branch 3.7.1 origin/3.7.1

Checking out a branch

After cloning and initial configuration, select the branch you want to work on, e.g.:

$ git checkout 3.7

You can list the available branches and display the active one with

$ git branch

Adding a port

$ cd ${PATH_TO_MY_CONTRIB_CLONE}
$ cp -r ${PATH_TO_UNCOMMITTED_STUFF}/myport .
$ git add -A myport
$ git commit -m "myport: initial commit"
$ git push

Note

Removing a port

$ cd ${PATH_TO_MY_CONTRIB_CLONE}
$ git rm -r someport
$ git commit -m "someport: dropped"
$ git push

Modifying a port

$ cd ${PATH_TO_MY_CONTRIB_CLONE}/someport
(edit files, e.g. Pkgfile and .footprint)
either:
    $ git add Pkgfile .footprint [...]
    $ git commit -m "someport: updated to 0.5.1"
or directly:
    $ git commit -m "someport: updated to 0.5.1" Pkgfile .footprint [...]
$ git push

If you run into trouble with the last command, because someone else has modified the repository in the meantime, run the following commands (i.e. to "fix" branch 3.7):

$ git fetch
$ git rebase origin/3.7
$ git log
$ git push

Merging branches

Let's say that you have two branches, 3.7 and 3.7.1. If you now modify one or more ports in branch 3.7, it's possible to merge these changes easily into another branch, say 3.7.1:

$ git checkout 3.7.1
$ git pull . 3.7

But use git pull with care as it will merge all changes (since the last merge) into branch 3.7.1 (prompting a warning on the mailing list).

Updating your working copy

$ cd ${PATH_TO_MY_CONTRIB_CLONE}
$ git fetch
updating branch 3.7:
    $ git checkout 3.7
    $ git rebase origin/3.7
updating branch 3.6:
    $ git checkout 3.6
    $ git rebase origin/3.6