Introduction

Here are some how-to guides to get you going more easily than the reference information linked via the tabs above. If you are a beginner, the the Pro Git book is another good resource.

This tutorial is aimed at end-users, rather than account admins. The admin documentation describes how to get an account set up, and this tutorial assumes your account is set up in the recommended way.

In the examples, I have used acct as a place-holder for the account you are using on this server, and spqr1 as a place-holder for your username; $ is your shell prompt and things you type are set in bold. For instance,

$ echo hello
hello
$

Get access

Find the contact details for your account's administrator in the list of accounts on this server.

You log in to git server through the relevant shared account - there are no per-user accounts. You are identified within this account by your ssh public key, which is used for access control.

If you need help getting started with ssh, the GitHub help pages have advice on checking for an existing ssh key , generating a new key , and using ssh-agent so you don't need to keep typing your passphrase .

Email your ssh public key to your account admin. You can copy-and-paste the output of this command into your message.

$ cat ~/.ssh/id_rsa.pub
ssh-rsa AAAAB3Nza[....]t+AoiMad2s spqr1

When your admin has added your key, you can check it is working with the help command.

$ ssh acct@git.csx.cam.ac.uk help
hello spqr1, this is acct@git running gitolite3 v3.NNN on git 2.NNN

list of remote commands available:

        D
        config
        create
        desc
        fork
        help
        info
        list-dangling-repos
        motd
        perms
        readme
        rename
        sskm

See https://git.csx.cam.ac.uk/ for documentation

You can run any of these commands without arguments to get information about how to use them. They are also described briefly in the user documentation.

Another notable command is info which gives you a list of the repositories that you have access to, and the permissions you have on each of them. R is for read access, W is for write access, and C means you can create new repositories.

$ ssh acct@git.csx.cam.ac.uk info
hello spqr1, this is acct@git running gitolite3 v3.NNN on git 2.NNN

     C  u/CREATOR/..*
 R W    testing

See https://git.csx.cam.ac.uk/ for documentation

You can see the same list of repositories (but without access permissions) on the Raven-authenticated part of the gitweb server at <https://git.csx.cam.ac.uk/i/acct/>. The page header on this authenticated internal view has /i/ in the breadcrumbs.

The unauthenticaed part of the gitweb server <https://git.csx.cam.ac.uk/x/acct/> shows only repos which allow anonymous access. The page header on this unauthenticated external view has /x/ in the breadcrumbs.

Click the i/x internal/external toggle in the breadcrumbs line to switch view.

Create a repo on the server

The first thing you might want do is create a repository on the server. The C permission displayed by the info command shows where you can create a repo. The runic utterance u/CREATOR/..* is a wildcard pattern which means spqr1 can create repositories with names like u/spqr1/repo.

$ ssh acct@git.csx.cam.ac.uk create u/spqr1/wombat
Initialized empty Git repository in /home/acct/repositories/u/spqr1/wombat.git/
'batch' mode started, waiting for input (run with '-h' for details).
Please hit Ctrl-C if you did not intend to do this.
$

The verbiage about "batch mode" and "Ctrl-C" comes from the perms command which is invoked behind the scenes to set up access permissions on your repository.

You can then clone this empty repository on to your local computer and start working on it.

$ git clone acct@git.csx.cam.ac.uk:u/spqr1/wombat
Cloning into 'wombat'...
warning: You appear to have cloned an empty repository.
Checking connectivity... done.
$ cd wombat
$ echo 'wombats are marsupials' >fact
$ git add fact
$ git commit -m 'a fact about wombats'
[master (root-commit) 4e6f531] a fact about wombats
 1 file changed, 1 insertion(+)
 create mode 100644 fact
$ git push origin master
Counting objects: 3, done.
Writing objects: 100% (3/3), 233 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To acct@git.csx.cam.ac.uk:u/spqr1/wombat
 * [new branch]      master -> master
$

You can see your new repository is listed on the gitweb internal view, and you can view its commit logs at <https://git.csx.cam.ac.uk/i/acct/u/spqr1/wombat.git>. No-one else can see it, though.

Upload a repo to the server

More commonly, you will already have a repo which you want to upload to the server. For example, say you have been doing some work on echidnas:

$ cd
$ git init echidna
Initialized empty Git repository in /home/spqr1/echidna/.git/
$ cd echidna
$ echo 'echidnas are monotremes' >fact
$ git add fact
$ git commit -m 'a fact about echidnas'
[master (root-commit) f1c5f72] a fact about echidnas
 1 file changed, 1 insertion(+)
 create mode 100644 fact
$

You want to upload this to the git server. First, create the target repository. This has to be done explicitly to avoid messes that would occur if repositories were automatically created by mistyped git push commands.

$ ssh acct@git.csx.cam.ac.uk create u/spqr1/echidna
Initialized empty Git repository in /home/acct/repositories/u/spqr1/echidna.git/
'batch' mode started, waiting for input (run with '-h' for details).
Please hit Ctrl-C if you did not intend to do this.
$

Then you tell your local repository about its remote counterpart. The name "origin" is the conventional remote name, same as you get from using git clone.

$ git remote add origin acct@git.csx.cam.ac.uk:u/spqr1/echidna
$

Then push your local repository to its new remote, and use the --set-upstream option to tell git that in the future you want to push the same way.

$ git push --set-upstream origin master
Counting objects: 3, done.
Writing objects: 100% (3/3), 234 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To acct@git.csx.cam.ac.uk:u/spqr1/echidna
 * [new branch]      master -> master
Branch master set up to track remote branch master from origin.
$

You can now work on the repository as if you had cloned it:

$ echo 'echidnas are spiny' >>fact
$ git commit -am 'another fact'
[master d7092e8] another fact
1 file changed, 1 insertion(+)
$ git push
Counting objects: 3, done.
Writing objects: 100% (3/3), 265 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To acct@git.csx.cam.ac.uk:u/spqr1/echidna
f1c5f72..d7092e8  master -> master
$

Change access permissions

Part of the point of this git server is to support collaboration, so the next thing you want to do is give your colleagues access permissions to your repositories. The perms command has some terse usage instructions.

$ ssh acct@git.csx.cam.ac.uk perms

perms -- list or set permissions for user-created ("wild") repo.

Usage summary:
    ssh git@host perms <repo> -l
        # list current permissions on repo
    ssh git@host perms <repo> -lr
        # list available roles and their access rights

    ssh git@host perms <repo> + <rolename> <username>
        # change permissions: add a user to a role
    ssh git@host perms <repo> - <rolename> <username>
        # change permissions: remove a user from a role

Examples:
    ssh git@host perms my/repo + READERS alice
    ssh git@host perms my/repo + WRITERS bob

----
There is also a batch mode useful for scripting and bulk loading.  Do not
combine this with the +/- mode above.  This mode also accepts an optional "-c"
flag to create the repo if it does not already exist (assuming $GL_USER has
permissions to create it).

Examples:
    cat copy-of-backed-up-gl-perms | ssh git@host perms <repo>
    cat copy-of-backed-up-gl-perms | ssh git@host perms -c <repo>

$

By default no-one has any special permissions on your repo. (The -l is a lower-case L meaning "list".)

$ ssh acct@git.csx.cam.ac.uk perms u/spqr1/echidna -l
$

You can give access to a specific user as follows. RW+ is full read/add/delete access.

$ ssh acct@git.csx.cam.ac.uk perms u/spqr1/echidna + RW+ fjc55
$ ssh acct@git.csx.cam.ac.uk perms u/spqr1/echidna -l
RW+ fjc55
$

But usually it is better to use groups rather than individual users. So we'll remove fjc55, and add your group instead.

You must first ask your account admin to set up the groups that you need.

Let's say you are working in the "esoteric research" group, and your account admin has created an @esoteric group in gitolite for you.

$ ssh acct@git.csx.cam.ac.uk perms u/spqr1/echidna - RW+ fjc55
$ ssh acct@git.csx.cam.ac.uk perms u/spqr1/echidna + RW+ @esoteric

If you want to grant anonymous access to a repository, give read access to the @all group:

$ ssh acct@git.csx.cam.ac.uk perms u/spqr1/echidna + R @all
$ ssh acct@git.csx.cam.ac.uk perms u/spqr1/echidna -l
R @all
RW+ @esoteric
$

On the gitweb server you will now see that the /i/ authenticated repo list has an echidna and a wombat, whereas the /x/ anonymous page only has an echidna.

Configure gitweb

You can add more information about your repository to the gitweb list. You usually do this by setting git config variables.

You can set a description to be included in your account's repository list,

$ ssh acct@git.csx.cam.ac.uk config u/spqr1/echidna \
    gitweb.description "Information about echidnas"
$

And you can add a README to be included on the repo's summary page. This file will become visible when you next push the repo to the server. (If you already have a README file then just setting the config variable is not enough to make it appear.)

$ ssh acct@git.csx.cam.ac.uk config u/spqr1/echidna \
    hooks.readme-file README.md
$ cat >README.md
Echidnas are weird
==================

Here are some facts about them
^D
$ git add README.md
$ git commit -m 'add a README file'
[master 47b856b] add a README file
 1 file changed, 4 insertions(+)
 create mode 100644 README.md
$ git push
Counting objects: 3, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 326 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
To acct@git.csx.cam.ac.uk:u/spqr1/echidna
   d7092e8..47b856b  master -> master
$

Now you can see it on the web server when you go to <https://git.csx.cam.ac.uk/i/acct/u/spqr1/echidna.git>.

Configure multimail

You can also tell the git server to send you email whenever anyone pushes to your repository.

$ ssh acct@git.csx.cam.ac.uk config u/spqr1/echidna \
    multimailhook.mailinglist spqr1@cam.ac.uk
$ echo 'echidnas lay eggs' >>fact
$ git commit -am 'a weird fact'
[master b3ac04f] a weird fact
 1 file changed, 1 insertion(+)
$ git push
Counting objects: 3, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 311 bytes | 0 bytes/s, done.
Total 3 (delta 0), reused 0 (delta 0)
remote: Sending notification emails to: spqr1@cam.ac.uk
To acct@git.csx.cam.ac.uk:u/spqr1/echidna
   8d4044c..b3ac04f  master -> master
$

You can see in the push output above that the server said it was sending you email. If you check your inbox, you can see one message which gives a summary of the push, plus one message for each commit.

Remove repositories

If you have been trying out these examples in your own account, you may want to clean away the tutorial repositories.

The D command is for deleting repositories. For safety, it requires two steps.

$ ssh acct@git.csx.cam.ac.uk D
Usage:    ssh git@host D  

The whimsically named "D" command deletes repos ("D" is a counterpart to the
"C" permission which lets you create repos.  Which also means that, just
like "C", it only works for wild repos).

There are two kinds of deletions: 'rm' removes a repo completely, while
'trash' moves it to a trashcan which can be recovered later (upto a time
limit that your admin will tell you).

The 'rm', 'lock', and 'unlock' subcommands:
    Initially, all repos are "locked" against 'rm'.  The correct sequence is
        ssh git@host D unlock repo
        ssh git@host D rm repo
    Since the initial condition is always locked, the "lock" command is
    rarely used but it is there if you want it.

The 'trash', 'list-trash', and 'restore' subcommands:
    You can 'trash' a repo, which moves it to a special place:
        ssh git@host D trash repo
    You can then 'list-trash'
        ssh git@host D list-trash
    which prints something like
        repo/2012-04-11_05:58:51
    allowing you to restore by saying
        ssh git@host D restore repo/2012-04-11_05:58:51

$ ssh acct@git.csx.cam.ac.uk D unlock u/spqr1/echidna
'u/spqr1/echidna' is now unlocked
$ ssh acct@git.csx.cam.ac.uk D rm u/spqr1/echidna
'u/spqr1/echidna' is now gone!
$ ssh acct@git.csx.cam.ac.uk D unlock u/spqr1/wombat
'u/spqr1/wombat' is now unlocked
$ ssh acct@git.csx.cam.ac.uk D rm u/spqr1/wombat
'u/spqr1/wombat' is now gone!
$