Getting access

Check the list of accounts on this server to find out if there is one for your part of the University and who manages the account. Each account is shared by all the members of the group that it belongs to - there are no per-user logins.

To get access to the account, send the following to an account admin:

  • Your user name (CRSID).
  • Your ssh public key.

Support

If you have questions about using git or the git service, please contact your account admins in the first instance.

You can read a copy of the git manual on this server.

You may wish to subscribe to the cs-git-users mailing list.

Repository locations

The account admins determine who has access to which repositories in their account. They can also allow unauthenticated public access to some repositories. Repositories can be viewed in a web browser using gitweb, as well as cloned using git itself.

The following subsections describe which URLs provide which kind of access. In the URLs, acct is a place-holder for the account name and repo is a place-holder for the repository name.

Authenticated users

  • Read/write access using git and ssh:
    • git clone ssh://acct@git.csx.cam.ac.uk/repo
    • git clone acct@git.csx.cam.ac.uk:repo
    • List repos accessible this way:
      ssh acct@git.csx.cam.ac.uk info
  • View in browser with Raven authentication:
    • https://git.csx.cam.ac.uk/i/acct/repo
    • List repos accessible this way:
      https://git.csx.cam.ac.uk/i/acct/
    • You can switch to the external view by clicking the i in the breadcrumbs.

Anonymous users

  • Read-only access to public repositories using git:
    • git clone git://git.csx.cam.ac.uk/acct/repo
  • View public repositories in browser:
    • https://git.csx.cam.ac.uk/x/acct/repo
    • List repos accessible this way:
      https://git.csx.cam.ac.uk/x/acct/
    • You can switch to the internal view by clicking the x in the breadcrumbs.

Server commands

There are a number of commands you can run on the server. You can run a command without parameters to get help on how to use it. In the following replace acct with your account name.

  • ssh acct@git.csx.cam.ac.uk help
    • Produces a list of commands that you can run.
  • ssh acct@git.csx.cam.ac.uk info
    • Produces a list of repositories that you have access to, and what kinds of access you are permitted. Use the -lc option to list repo creators and/or the -ld option to list repo descriptions.
  • ssh acct@git.csx.cam.ac.uk sskm
    • Self-service key management. This allows you to update the ssh keys you use to log in to the account without bothering an account admin. See the sskm command documentation for details.
  • ssh acct@git.csx.cam.ac.uk list-dangling-repos
    • To help admins keep their accounts tidy.

Wild repos

The other commands are for manipulating user-managed "wild" repositories. In the output of the info command you will usually see a line like this:

      C  u/CREATOR/..*
This means you have permission to create repositories without bothering the account admins, provided they have names of the form u/spqr2/wombat where spqr2 is your user name and wombat is the repository name. You can run these commands without parameters to get more detailed help.

  • ssh acct@git.csx.cam.ac.uk create repo
    • Create an empty wild repo.
    • (Gitolite's auto-create-on-pull is turned off on this server to avoid accidents.)
  • ssh acct@git.csx.cam.ac.uk fork old new
    • Create a wild repo containing a copy of another repo.
  • ssh acct@git.csx.cam.ac.uk rename old new
    • Change the name of a wild repo.
  • ssh acct@git.csx.cam.ac.uk desc repo text
    • Set the repository's gitweb description.
  • ssh acct@git.csx.cam.ac.uk readme repo
  • ssh acct@git.csx.cam.ac.uk config repo options
  • ssh acct@git.csx.cam.ac.uk D subcommand repo
    • Delete a wild repo.
  • ssh acct@git.csx.cam.ac.uk perms args
    • Edit who has permission to do what to a wild repo.

Permissions and roles

The perms command works in terms of "roles".

There is a special OWNERS role. Anyone you add to that role is also able to change the repo's perms.

Other roles are configured by your account admin. You can use the perms -lr option find out which roles correspond to which permissions. Our recommended setup gives you:

    perm    ref             role
    ----    ---             ----
    RW+     --any-- =       OWNERS
    -       --any-- =       DENY
    R       --any-- =       R
    RW      --any-- =       RW
    RW+     --any-- =       RW+

This means:

  • The DENY role denies access to the repo. You might want to put the @public group in this role to ensure a repo remains private.
  • The R role grants read access. You might want to put the @all group in this role to allow anonymous access.
  • The RW role allows users to add data to a repository by pushing commits and adding new branches and tags.
  • The RW+ role has the same rights as the RW role, and also allows users to remove data from a repository by rewinding branches and deleting branches and tags.
  • These permissions apply to any ref (every branch and tag) in the repository.

Your account admins can define groups in the gitolite.conf file, and you can add groups to roles as well as individual users. There are also built-in group definitions like:

 @public = gitweb daemon
 @ssh = [ all known users of the account ]
 @all = [ absolutely everyone ]

The admin documentation on groups explains the asymmetry in controlling anonymous access, where you grant access to the @all group but deny access to the @public group. It also has more information about the special groups listed above. However, the @lookup_ pseudo-groups do not work with the perms command.

Access control for groups

When your account admin has made a wild repository area for your group, there's a basic recipe you can follow to set up the permissions after you create a repository. Say your group is called "wombles":

  • Create a repo:
    • ssh acct@git.csx.cam.ac.uk create wombles/orinoco
  • Make your fellow wombles OWNERS of the repo, so they have read/write access and can adjust its perms:
    • ssh acct@git.csx.cam.ac.uk perms wombles/orinoco + OWNERS @wombles
  • Give read access to your other colleagues:
    • ssh acct@git.csx.cam.ac.uk perms wombles/orinoco + R @ssh

git config variables

You can set the following git config variables using the config command, to adjust gitweb or to set up git push hooks.

  • To configure gitweb repository listings and summaries (see the gitweb manual for details):
    • gitweb.owner
      • (defaults to the creator of a wild repo)
    • gitweb.category
      • (defaults to the repo's parent directory, if any)
    • gitweb.description
  • To configure gitweb README files (see below):
    • hooks.readme-file
    • hooks.readme-type
  • To configure push notification email (see below):
    • multimailhook.*
  • To configure remote post-receive hooks (see the admin documentation):
    • hooks.remote-http-get
    • hooks.remoteuser

The config command does not work for managed repositories; instead an admin must add the config settings to gitolite.conf.

README files for gitweb

There are two ways to make gitweb display a README.html file on a repository's summary page: by setting some git config hook variables on the server, or by running the readme command.

The readme hook

If you would like gitweb to display a README file which you have committed to your repository, set the config hooks.readme-file variable to the filename. If the filename does not have a .txt, .html, or .md extension, set the config hooks.readme-type variable to "text", "html", or "markdown". For example,

 ssh acct@git.csx.cam.ac.uk config repo hooks.readme-file README.md

When you push a change to the repository, its README is automatically updated. If hooks.readme-file is "-" then it will be deleted on the next push.

The readme hook works for both wild and managed repositories. For managed repositories, an admin must add the config settings to gitolite.conf.

The readme command

The readme command allows you to put an HTML fragment on the server which does not need to be committed to the repository. It can be a bit quicker than the hook, but it only works for wild repositories and it does not update the README automatically. As with other server commands you can get usage instructions by running it without arguments. For example,

 markdown README.md | ssh acct@git.csx.cam.ac.uk readme repo set

Push notification email with multimail

It is often helpful to get automated email notification of changes to a shared repository. You can configure the multimail hook to do this. It has many settings which are described in the multimail README.

To use multimail you must set the git config multimailhook.mailinglist variable. If you only set this variable, each push will generate a summary message describing each changed branch or tag, plus a message describing each new commit.

You can turn off the per-commit messages, and include a log of the patches in the summary messages instead, with the following settings:

 ssh acct@git.csx config repo multimailhook.commitlist none
 ssh acct@git.csx config repo multimailhook.refchangeshowlog true
 ssh acct@git.csx config repo multimailhook.logopts "--decorate --patch"

You may set any of the other git config multimailhook variables except for the following which are restricted for security reasons:

  • multimailhook.reponame
  • multimailhook.environment
  • multimailhook.mailer
  • multimailhook.sendmailcommand
  • multimailhook.smtpserver