list-non-core.mkd

   1 <!-- options: toc -->
   2
   3 % non-core features shipped with gitolite
   4
   5 include sidebar-toc
   6
   7 **Important Notes on "non-core" features**:
   8
   9 1.  The ["non-core" gitolite][non-core] page is the starting point for all
  10     information about ... non-core gitolite :)
  11
  12 2.  This page decribes many of the non-core features that come with gitolite.
  13     If a non-core feature is shipped with gitolite, but information about it
  14     is not found in this page, it can be found within the source code; please
  15     look there.
  16
  17     [Commands][], however, have some extra magic, which is not available to
  18     the other types of non-core programs:
  19
  20       * Running the command with a single `-h` option (i.e., `gitolite
  21         <command> -h` or `ssh git@host <command> -h`), will display a suitable
  22         message.  Please report a bug to me if one of them doesn't.
  23
  24       * Running 'help', (either as `gitolite help` on the server, or `ssh
  25         git@host help` remotely), will give you a list of commands you are
  26         allowed to run.
  27
  28 3.  Non-core code is **meant** to be [localised for your site][localcode] if
  29     you don't like what the shipped version does.  You can even maintain it
  30     [within your gitolite-admin repo][pushcode] if you wish.
  31
  32 # commands
  33
  34 This is a list of commands that are available in gitolite, with brief
  35 descriptions and, if available, a link to more detailed information.  Note
  36 that in most cases running it with `-h` will give you enough to work with.
  37
  38 Also note that not all of these commands are available remotely.
  39
  40 (The more common/important commands are in bold).
  41
  42   * *access* -- print or test access rights for repo/user
  43   * *create* -- create a wild repo
  44   * *creator* -- print or test creator name for wild repo
  45   * *D* -- lets you *D*elete wild repos created using the *C* permission :)
  46   * **desc** -- show/set description for wild repo
  47   * *fork* -- fork a repo on the server.  This uses the `-l` option to git
  48     clone, so it runs really fast
  49   * *git-config* -- print (or text existence of) 'config' values in the repo.
  50     (Don't forget that `option foo.bar = 1` is merely syntactic sugar for
  51     `config gitolite-options.foo.bar = 1`, so this can be used to query
  52     gitolite options also
  53   * **help** -- see note 1 at the top of this page
  54   * *htpasswd* -- sets your htpasswd
  55   * **[info][]** -- print git/gitolite version, list repos you have access to
  56   * *[lock][locking]* -- lock binary files for exclusive use (in combination
  57     with the 'lock' VREF)
  58   * *[mirror][sync]* -- manually mirror a repo to a slave
  59   * **[perms][]** -- list or set permissions for wild repo
  60   * *[push][bypass]* -- push a gitolite repo locally, bypassing gitolite
  61   * *rsync* -- bundling support for gitolite
  62   * *sshkeys-lint* -- look for potential problems in ssh keys
  63   * *[sskm][]* -- self-service key management
  64   * *sudo* -- allows an admin (i.e., someone who has push rights to the
  65     'gitolite-admin' repo) to run any remote command as some other user.  This
  66     is useful, for example, when a user claims he is unable to access a repo,
  67     and you need to check the 'info' output for him, etc.  However, it does
  68     not work the other way, sorry!
  69   * *symbolic-ref* -- run `git symbolic-ref` on a repo, remotely
  70   * *who-pushed* -- determine who pushed a given commit
  71   * *writable* -- disable/enable writes to specific repo (or all repos, if
  72     you're an admin)
  73
  74 # syntactic sugar
  75
  76 The following "sugar" programs are available:
  77
  78   * *continuation-lines* -- allow C-style backslash escaped continuation lines
  79     in the conf file
  80   * *keysubdirs-as-groups* -- use the last component of the sub-directory name
  81     within keydir as a group name
  82   * **macros** -- simple line-wise macro processor
  83
  84 # triggers
  85
  86 Here's a list of **features** that are enabled by [triggers][], or a
  87 combination of a trigger and something else, like a command.
  88
  89   * *Alias* -- allow repos to have aliases
  90   * *AutoCreate* -- deny auto-create of wild repos on R or RW access
  91   * *bg* -- allow long running post-compile/post-create jobs to be
  92     backgrounded
  93   * *CpuTime* -- CPU and elapsed times for gitolite+git
  94   * **[Mirroring][mirroring]** -- mirroring all or some repos
  95   * *Motd* @@gray((v3.6.1+))@@ -- allows printing a message of the day to
  96     STDERR in ssh mode
  97   * *[partial-copy][]* -- simulated read control for branches (in combination
  98     with the partial-copy VREF)
  99   * *RefexExpr* -- (in combination with VREF/refex-expr) logical expressions
 100     over refexes, like "refex-1 and not refex-2".  (Example: changing file
 101     'foo' but not on 'master' branch)
 102   * *renice* -- renice the git operation
 103   * *RepoUmask* -- repo-specific umask settings
 104   * *Shell* -- see "giving shell access to gitolite users" in the [ssh
 105     troubleshooting and tips][sts] page.  (Internally enables the
 106     'ssh-authkeys-shell-users' trigger also).
 107   * *ssh-authkeys-split* -- split pubkey files with multiple keys into
 108     separate files with one pubkey each
 109   * *update-description-file* -- if you want the 'description' file to be
 110     updated instead of the 'gitweb.description' config entry (e.g. cgit users)
 111   * *upstream* -- manage local, gitolite-controlled, copies of read-only
 112     upstream repos
 113
 114 In addition, the following post-compile trigger scripts are enabled by
 115 default, so are included here only for completeness and in case you wish to
 116 disable them:
 117
 118   * ssh-authkeys -- process keys in keydir/ and add/update appropriate lines
 119     to the authorized keys file
 120   * update-git-configs -- run `git config` in each repo to add/update entries
 121     as needed
 122   * update-git-daemon-access-list -- create/delete the 'git-daemon-export-ok'
 123     files in each repo as needed
 124   * update-gitweb-access-list -- create the "projects.list" file that gitweb
 125     uses to determine what repos to show/not show
 126
 127 # VREFs
 128
 129 VREFs are a complex topic and have their [own page][vref] with lots more
 130 details.  However, here's a list of VREFs shipped with gitolite:
 131
 132   * *[COUNT][]* -- restrict pushes by number of changed or new files pushed
 133   * *EMAIL-CHECK* -- check if all new commits are authored by the person pushing
 134   * *[lock][locking]* -- lock binary files for exclusive use (in combination
 135     with the 'lock' command)
 136   * *MAX\_NEWBIN\_SIZE* -- restrict by size of new binary files (helps catch
 137     people checking in random PDFs, JARs, WARs, etc.)
 138   * **[NAME][]** -- restrict pushes by dir/file name
 139   * [partial-copy][] -- simulated read control for branches (in combination
 140     with the partial-copy trigger)
 141   * *refex-expr* -- (in combination with the refex-expr trigger) logical
 142     expressions over refexes, like "refex-1 and not refex-2".  (Example:
 143     changing file 'foo' but not on 'master' branch)
 144   * *[VOTES][votes]* -- voting on commits a la gerrit
 145
 146 # details on some non-core programs
 147
 148 These non-core programs needed more detail than could be provided in the
 149 source code, but did not fit anywhere else neatly enough.
 150
 151 ## partial-copy: selective read control for branches {#partial-copy}
 152
 153 Git (and therefore gitolite) cannot do selective read control -- allowing
 154 someone to read branch A but not branch B.  It's the entire repo or nothing.
 155
 156 @@box-r(Gerrit Code Review can do that, but that is because they have their
 157 own git (as well as their own sshd, and so on).  If code review is part of
 158 your access control decision, you really should consider Gerrit anyway.)@@
 159
 160 The standard answer you get when you ask is "use separate repos" (where one
 161 contains all the branches, and one contains a subset of the branches).  This
 162 is nice in theory but in practice, when people are potentially *pushing* to
 163 both repos, you need to figure out how to keep them in sync.
 164
 165 Gitolite can now help you do this.  Note that this is only for branches; you
 166 can't do this for files and directories.
 167
 168 Here's how:
 169
 170 1.  enable 'partial-copy' in the ENABLE list in the rc file.
 171
 172 2.  for each repo "foo" which has secret branches that a certain set of
 173     developers (we'll use a group called `@temp-emp` as an example) are not
 174     supposed to see, do this:
 175 .#! conf/vim-color
 176         repo foo
 177             # rules should allow @temp-emp NO ACCESS
 178
 179         repo foo-partialcopy-1
 180             -   secret-branch               =   @temp-emp
 181
 182             # other rules; see notes below
 183
 184             -   VREF/partial-copy           =   @all
 185             config gitolite.partialCopyOf   =   foo
 186 .end
 187
 188     <!-- the above block uses Unicode 00A0 (space) to make it look like one block!  -->
 189
 190     **IMPORTANT NOTES**:
 191
 192       * if you're using other VREFs, **make sure** this one is placed at the
 193         end, after all the others.
 194
 195       * remember that any change allowed to be made to the partial-copy repo
 196         will propagate to the main repo so make sure you use other rules to
 197         restrict pushes to other branches and tags as needed.
 198
 199 And that should be it.  **Please test it and let me know if it doesn't work!**
 200
 201 WARNINGS:
 202
 203   * If you change the config to disallow something that used to be allowed,
 204     you should delete the partial repo on the server and then run `gitolite
 205     compile; gitolite trigger POST_COMPILE` to let it build again.
 206
 207   * Not tested with smart http; probably won't work.
 208
 209   * Also not tested with mirroring, or with wild card repos.