=======================
Gitolite documentation:
=======================

.. contents::

Overview:
=========

Gitolite is an administrtive front end to git that that allows us to more 
efficiently mirror the repos and to provide by-name access to various 
repositories through the use of ssh keys.  It also allows us to create 
personal repos so we can employ version control on our own work.

This document will expand over time to include information on repo mirroring
and other lessons learned regarding gitolite; however, for the time being,
it'll concentrate on personal repos.

Personal Repos:
===============

Personal repo overview:
-----------------------

We have a number of pre-defined repos for root/OS related information, 
filemover, and xymon.  Those have been used for several months now and no 
one seems to have an issue using them.  Those *standard* repos are defined in 
the gitolite configuration files.

Gitolite also allows creating and destroying adhoc repos that are "owned" by
the user creating them.  These repos aren't even visible to other people
unless the creator allows access.  These types of repos are generally used
as personal repos to place our own work under version control.  

As an example, I have the following personal repos defined in gitolite: ::

    $ ssh git@nap1151 info
    hello dkoleary, this is git@napsinfmgmt1151 running gitolite3 v3.6.2-4-g2471e18 on git 1.7.1
    
         C  private/CREATOR/..*
     R W    filemover/filemover_dr
     R W    filemover/filemover_prod
     R W    gitolite-admin
     R W    private/dkoleary/bin
     R W    private/dkoleary/docs
     R W    private/dkoleary/etc
     R W    private/dkoleary/hp_support
     R W    private/dkoleary/projects
     R W    private/dkoleary/security
     R W    private/dkoleary/ssh
     R W    root/apps
     R W    root/docs
     R W    root/pwd
     R W    root/scripts
     R W    root/security
     R W    xymon

Notice when Jayu executes the info command, my repos aren't visible: ::

    hello jsenchaudhuri, this is git@napsinfmgmt1151 running gitolite3 v3.6.2-4-g2471e18 on git 1.7.1
    
    C private/CREATOR/..*
    R W filemover/filemover_dr
    R W filemover/filemover_prod
    R W root/apps
    R W root/docs
    R W root/pwd
    R W root/scripts
    R W root/security
    R W xymon

Creating personal repos:
------------------------

The process to create personal repos is a little more involved; but, not by 
much.  

1.  Create a normal local repo, populate it, and commit the work. ::

        $ git init
        Initialized empty Git repository in /ignite/dkoleary/temp/150218/.git/
        $ git add -A
        $ git commit -am'testing repo'
        [master (root-commit) 0027a37] testing repo
         3 files changed, 11 insertions(+), 0 deletions(-)
         create mode 100644 MPI_SSH_Pub
         create mode 100644 gscapescp.pub
         create mode 100644 gscapescp1.pub

2.  Push the repo to gitolite specifying the new private repo and the master
    branch: ::

        $ git push git@nap1151:private/dkoleary/testing master
        Initialized empty Git repository in /opt/app/git/repos/private/dkoleary/testing.git/
        Counting objects: 4, done.
        Delta compression using up to 4 threads.
        Compressing objects: 100% (4/4), done.
        Writing objects: 100% (4/4), 676 bytes, done.
        Total 4 (delta 1), reused 0 (delta 0)
        To git@nap1151:private/dkoleary/testing
         * [new branch]      master -> master

3.  Update the remote parameter to enable pulls and pushes: ::

        $ git remote add origin git@nap1151:private/dkoleary/testing

4.  From there, it's normal git commands to maintain the repo.

Enabling others to access a personal repo:
------------------------------------------

As noted above, normally people won't even see your personal repos.  However,
you can provide access to them if you want to collaborate on some work.  

Available permissions are READERS and WRITERS.  Those, I imagine, are self
explanatory

To allow access:
~~~~~~~~~~~~~~~~

::

    $ ssh git@nap1151 perms private/dkoleary/hp_support + WRITERS jroess

Once executed, Justin can now see my hp_support repo: ::

    [jroess@nap1d157 ~]$ ssh git@napsinfmgmt1151 info
    hello jroess, this is git@napsinfmgmt1151 running gitolite3 v3.6.2-4-g2471e18 on git 1.7.1
    
    C private/CREATOR/..*
    R W filemover/filemover_dr
    R W filemover/filemover_prod
    R W private/dkoleary/hp_support
    R W root/apps
    R W root/docs
    R W root/pwd
    R W root/scripts
    R W root/security
    R W xymon
    
To remove access:
~~~~~~~~~~~~~~~~~

Simply replace the '+' with a '-': ::

    $ ssh git@nap1151 perms private/dkoleary/hp_support - WRITERS jroess

Once done, Justin can no longer see the private repo: ::

    jroess@nap1d157 ~]$ ssh git@napsinfmgmt1151 info
    hello jroess, this is git@napsinfmgmt1151 running gitolite3 v3.6.2-4-g2471e18 on git 1.7.1
    
    C private/CREATOR/..*
    R W filemover/filemover_dr
    R W filemover/filemover_prod
    R W root/apps
    R W root/docs
    R W root/pwd
    R W root/scripts
    R W root/security
    R W xymon
    
Deleting personal repos:
------------------------

Deleting unneeded personal repos is a two step process: ::

    $ ssh git@nap1151 D unlock private/dkoleary/testing
    'private/dkoleary/testing' is now unlocked
    $ ssh git@nap1151 D rm private/dkoleary/testing
    'private/dkoleary/testing' is now gone!

And the repo is gone: ::

    $ ssh git@nap1151 info | grep testing
    $