docs/list-non-core.mkd

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