gitolite/doc/special.mkd

# special features and setups

----

[[TOC]]

----

## #writable disabling pushes to take backups

The `writable` command allows you to disable pushes to all repos or just the
named repo, in order to do file-system level things to the repo directory that
require it not to change, like using normal backup software.

Run `gitolite writable -h` for more info.

## #pers "personal" branches

"personal" branches are great for environments where developers need to share
work but can't directly pull from each other (usually due to either a
networking or authentication related reason, both common in corporate setups).

Personal branches exist **in a namespace** of their own.  The syntax is

        RW+ personal/USER/  =   @userlist

where the "personal" can be anything you like (but cannot be empty), and the
"/USER/" part is **necessary (including both slashes)**.

A user "alice" (if she's in the userlist) can then push any branches inside
`personal/alice/`.  Which means she can push `personal/alice/foo` and
`personal/alice/bar`, but NOT `personal/alice`.

(Background: at runtime the "USER" component will be replaced by the name of
the invoking user.  Access is determined by the right hand side, as usual).

Compared to using arbitrary branch names on the same server, this:

  * Reduces namespace pollution by corralling all these ad hoc branches into
    the "personal/" namespace.
  * Reduces branch name collision by giving each developer her own
    sub-hierarchy within that.
  * Removes the need to think about access control, because a user can push
    only to his own sub-hierarchy.

## delegating access control responsibilities

See [this][deleg].

## #keysonly using pubkeys obtained from elsewhere

If you're not managing keys via the gitolite-admin repo, but getting them from
somewhere else, you'll want to periodically "update" the keys.

To do that, first edit your rc file and add something like this:

    SSH_AUTHKEYS                =>
        [
            'post-compile/ssh-authkeys',
        ],

Then write a script that

  * gets all the keys and dumps them into `$HOME/.gitolite/keydir` (or into a
    subdirectory of it).

  * runs `gitolite trigger SSH_AUTHKEYS`.

Run this from cron or however you want.

## #pushhook updating hooks via the admin repo

Gitolite by default maintains the distinction between someone who can push to
the admin repo and someone who has shell access to the server.  As a result,
you cannot change any hooks merely by pushing the admin repo.

But some people don't care about this and want to do it anyway.  Besides,
there *is* one advantage: your hooks can also be versioned now.

So here's how to add/change hooks when you push the gitolite-admin repo:

1.  Put all common hooks in a new directory called 'common-hooks'.

2.  Create a trigger program called 'propagate-hooks' in 'src/triggers' that
    contains this:

        #!/bin/sh

        cd $GL_ADMIN_BASE
        cp -a common-hooks/* hooks/common

        gitolite setup --hooks-only

3.  Add this to the `POST_COMPILE` trigger list in the rc file.

And that should be it, pretty much.

If you have lots of repos this is inefficient -- because the hook fixup will
run on *any* change to the admin repo, even if the change has nothing to do
with hooks.

If you're concerned about this, put the script in 'src/commands' instead of
'src/triggers'.  (You might want to add some access control; see other
commands for inspiration, but it's not really needed in this case).

Then, whenever any hooks have changed, the admin can run

    ssh git@host propagate-hooks