req.mkd

   1 <!-- options: toc -->
   2
   3 % Before you start...
   4
   5 include sidebar-toc
   6
   7 This page talks about what you need to make sure you have before you install
   8 gitolite.  For most people, this is not a big deal, but please read through it
   9 anyway.  If you want to make sure, there's a section on trying it out safely.
  10
  11 # your skills
  12
  13   * If you're installing gitolite, you're a "system admin", like it or not.
  14     Since most people use the ssh mode, **[ssh][]** is therefore a necessary
  15     skill.  Please take the time to learn at least enough to get passwordless
  16     access working.
  17
  18   * You also need to be somewhat familiar with git itself.  You cannot
  19     administer a whole bunch of git repositories if you don't know the basics
  20     of git.
  21
  22     Please make sure you understand at least the following concepts: *bare
  23     versus non-bare repos, cloning a repo, making changes and committing them,
  24     pushing commits to a 'remote', the special remote called 'origin',
  25     difference between a fast-forward push and a rewind push, 'refs' (i.e.,
  26     branches and tags)*.
  27
  28     It also helps to understand git's hooks mechanism, git-config, and so on.
  29
  30   * Some familiarity with Unix and shells is probably required.
  31
  32   * [Regular expressions][regex] are a big part of gitolite in many places but
  33     familiarity is not necessary to do *basic* access control.
  34
  35 # your server
  36
  37   * Any Unix system with a posix compatible "sh" and a **sane** file system.
  38   * Git version 1.6.6 or later.
  39   * Perl 5.8.8 or later (see <https://lwn.net/Articles/348084/> if this does
  40     not seem to be enough).
  41   * Openssh (almost any version).  Optional if you're using [smart
  42     http][http].
  43   * A dedicated Unix userid to be the hosting user, usually "git" but it can
  44     be any user, even your own normal one.  (If you're using an RPM/DEB the
  45     install probably created one called "gitolite").
  46
  47 # you and your users' clients
  48
  49   * Openssh client.
  50   * Git 1.6.6 or later.  Almost any git client will work, as long as it knows
  51     how to use ssh keys and send the right one along.
  52
  53 # cautions and caveats
  54
  55 **Please take note of the following points**:
  56
  57   * If you're bringing existing repos into gitolite, please see
  58     [this][existing] first.
  59
  60   * Gitolite expects all the directories and files it manages/uses to be owned
  61     by the [hosting user][hu] and not have strange permissions and ownerships.
  62
  63   * Gitolite does NOT like it if you fiddle with [files and directories it
  64     cares about][files] in any way except as directed in the documentation.
  65
  66   * Gitolite depends on several system-installed packages: openssh, git, perl,
  67     sh being the main ones.  They should all be configured sensibly and with
  68     most of the normal defaults.  (For example, if your sshd config says the
  69     authorized keys file should be placed in some directory other than the
  70     default, expect trouble).
  71
  72 @@gray((For your entertainment, [here][no-way] are some requests I have
  73 refused over the years).)@@
  74
  75 # trying out gitolite safely {#trying}
  76
  77 If you're not sure if gitolite is right for you or your system, it's easy to
  78 take it for a trial run, in ssh mode, and play with all of its features
  79 (except mirroring).  This is very safe, and does not affect anything on your
  80 system permanently.
  81
  82 <font color="red">**WARNING: this will clobber [these files and
  83 directories][clobber] in your `$HOME`.  Ideally, you should use a throwaway
  84 userid**.</font>
  85
  86 Just create a **throw-away userid**, log in to it, then run these commands:
  87
  88     git clone git://github.com/sitaramc/gitolite
  89     cd gitolite
  90     prove t/ssh*
  91
  92 You will get an error that forces you to read `t/README` and set an env var
  93 before the test can proceed.  This is intentional; I've had people who don't
  94 pay attention to the "data loss" warning, and then complain that it was not
  95 prominent enough.  Forcing them to read a much smaller page appears to focus
  96 their attention better!
  97
  98 If it doesn't work, re-read this page to see if you may have missed something
  99 that gitolite requires, or ask for [support][contact].
 100
 101 If it works, you get a gitolite installation with 7 gitolite users ("admin",
 102 and "u1" through "u6").
 103
 104 Don't forget that the client and the server are all on the same user on the
 105 same machine; we're *simulating* 7 gitolite users using ssh keys!  (How?
 106 Maybe `~/.ssh/config` will give you a hint).
 107
 108 URLs look like `user:repo`, so for example you can clone the admin repo by
 109 `git clone admin:gitolite-admin`.  Remote commands look like `ssh u1 info`.
 110
 111 So start by cloning the admin repo, and try out whatever you want!