gitolite/master-toc.mkd

gitolite documentation -- master TOC

---

README

• Gitolite README

---

1000-words

• gitolite in pictures
  • installation and setup
  • adding users to gitolite
  • adding repos to gitolite
  • gitolite flow

---

admin-defined-commands

• admin defined commands
  • ADC background
  • ADC details
    • installing ADCs
    • user invocation
    • checking authorisation inside an ADC
    • checking arguments
    • passing unchecked arguments
  • "fake" repos and access control for non-git programs
  • anatomy of a command
  • example uses and sample commands in contrib/adc
    • the 'fork' ADC
    • deleting/trashing repos
    • enable/disable push access temporarily
  • how the ADC feature came about

---

admin

• administering and running gitolite
  • please read this first
  • adding users and repos
  • using hooks
    • custom hooks
    • hook chaining
    • environment variables available to hooks
    • "gl-post-init" hook
    • "gl-pre-git" hook
  • other features
    • moving pre-existing repos into gitolite
    • moving the whole thing from one server to another
    • custom git config

---

auth

• authentication versus authorisation
  • but... but... you have all that ssh stuff in there!
  • so you're basically saying you won't support "X"
  • appendix: how to use other authentication systems with gitolite

---

big-config

• what is a "big-config"
  • when/why do we need it?
    • the problem
  • how do we use it?
    • access rules for groups
    • access rules for individual repos (split config)
  • what are the downsides?
  • other optimisations
    • disabling various defaults
    • optimising the authkeys file
  • storing usergroup information outside gitolite (like in LDAP)
    • why
    • how
  • implementation notes
  • config listings
    • compiled config with big-config disabled
    • compiled config with big-config enabled

---

delegation

• delegating access control responsibilities
  • lots of repos, lots of users
  • how to use delegation
    • the subconf command
    • backward compatibility
  • security notes
    • group names
    • delegating pubkeys

---

developer-notes

• developer/patch maintainer notes
  • general stuff
  • the rc file
  • modules
  • that 'bindir' thing
    • from perl
    • from shell
    • OUTLIER!
  • special types of setups
    • Fedora
• Why v2?

---

gitolite-and-ssh

• how gitolite uses ssh
  • ssh basics
  • how does gitolite use all this ssh magic?
    • restricting shell access/distinguishing one user from another
    • restricting branch level actions

---

gitolite.conf-by-example

• gitolite.conf -- by example
  • general notes
  • extremely brief regex overview
  • basic access control
  • advanced access control
    • "deny" rules
    • rule accumulation
    • gitweb and daemon

---

gitolite.conf

• the access control file gitolite.conf
  • syntax
    • continuation lines
    • include files
  • basic access control
    • how rules are matched
    • branches, tags, and specifying "refex"es
    • groups
      • the special @all group
  • advanced access control
    • "deny" rules
      • warnings and required reading
      • "deny" rules for refs in a repo
      • "deny" rules for the entire repo
    • creating and deleting branches
  • summary: permissions
  • other tips
    • personal branches
    • rule accumulation
    • specifying gitweb and daemon access
    • repo specific git config commands

---

gitolite-gitweb-http-backend

• how to set up gitolite+gitweb+ssh+http-backend
  • NAME
  • DESCRIPTION
  • EXAMPLE ENVIRONMENT
  • GITOLITE SETUP
    • gitolite.rc
    • gitolite.conf
  • APACHE SETUP
    • suexec
    • Gitweb
    • Virtual Host
  • VALIDATION
  • ADDITIONAL RESOURCES
  • AUTHOR

---

gitolite.rc

• configuring gitolite's advanced features -- the .gitolite.rc file
  • variables that should not be touched at all
  • most often used/changed variables
  • variables with an efficiency/performance impact
  • variables with a security impact
  • less used/changed variables
  • rarely changed variables
  • constants that aren't!

---

hook-propagation

• hook propagation in gitolite
  • hooks used by gitolite
  • where do I (the admin) put the hooks?
    • the GL_PACKAGE_HOOKS directory
    • the $HOME/.gitolite directory
    • why two places?
    • special case: the "non-root" method
  • when do hooks propagate?

---

http-backend

• how to setup gitolite to use smart http mode
  • WARNINGS, plus stuff I need help with
  • additional requirements
  • detailed instructions
    • install gitolite under "apache"
    • setup apache
  • usage
  • allowing anonymous access
  • ssh + http access and the GIT_HTTP_EXPORT_ALL variable

---

index

• Hosting git repositories
  • quick install
  • what should you read?
    • what do the other docs contain
  • what is gitolite?
  • why is gitolite needed?
  • why did I write it?
    • some more features
  • security
  • contact and license

---

install

• gitolite installation
  • installing and upgrading gitolite
    • package method
    • non-root method
      • upgrading from from-client method to non-root method
    • root method
    • upgrading
  • if you run into trouble...
    • common install problems
    • naming conventions used
    • helpful background information
    • requirements
      • client/workstation
      • server
      • technical skills
    • getting the gitolite software
      • getting a tar file from a clone
  • appendixes
    • appendix a: PATH issues for gl-setup
    • appendix b: cleaning out a botched install
    • appendix c: uninstalling gitolite completely

---

migrate

• migrating from gitosis to gitolite

---

mirroring

• mirroring gitolite servers
  • why
  • RULE NUMBER ONE!
  • concepts and terminology
  • setting up mirroring
    • IMPORTANT cautions
    • setup and usage
      • server level setup
      • repository level setup
    • commands to (re-)sync mirrors
  • details
    • the conf/gitolite.conf file
    • redirecting pushes
  • example setups
    • non-autonomous
    • non-autonomous with local repos
    • semi-autonomous
    • autonomous
  • discussion
    • problems with the old mirroring model
    • the new mirroring model
  • appendices
    • appendix A: example cronjob based mirroring
    • appendix B: efficiency versus paranoia

---

mob-branches

• mob branches in gitolite

---

nagp

• ...not a gitolite problem!
  • ssh
  • git
  • windows
  • apple
  • just say NO!
    • behind my back
  • that's outrageous

---

packaging

• packaging gitolite

---

progit-article

• (master copy of progit chapter on gitolite)
  • Gitolite ##
    • Installing ###
    • Customising the Install ###
    • Config File and Access Control Rules ###
    • Advanced Access Control with "deny" rules ###
    • Restricting pushes by files changed ###
    • Personal Branches ###
    • "Wildcard" repositories ###
    • Other Features ###

---

report-output

• output of the "info" and "expand" commands
  • the "info" command
    • interpreting the output
    • using patterns to limit output
    • side note: openssh 5.6
  • the "expand" command

---

ssh-troubleshooting

• ssh troubleshooting
  • IMPORTANT -- READ THIS FIRST
    • caveats
    • naming conventions used
    • taking stock -- relevant files and directories
    • normal gitolite key handling
  • (Other resources)
  • common ssh problems
  • step by step
  • random tips, tricks, and notes
    • giving shell access to gitolite users
    • losing your admin key
    • simulating ssh-copy-id
    • problems with using non-openssh public keys
    • windows issues
  • appendix 1: ssh daemon asks for a password
  • appendix 2: which key is which -- running sshkeys-lint
    • typical cause(s)
  • appendix 3: ssh client may not be offering the right key
  • appendix 4: host aliases
  • appendix 5: why bypassing gitolite causes a problem

---

tips-notes

• assorted tips and notes
  • common errors and mistakes
  • other errors, warnings, notes...
    • cloning an empty repo
    • @all syntax for repos
  • features
    • syntax and normal usage
      • one user, many keys
        • old style multi keys
    • security, access control, and auditing
      • two levels of access rights checking
      • better logging
      • delegating parts of the config file
    • convenience features
      • what repos do I have access to?
      • support for git installed outside default PATH
      • "personal" branches
      • custom hooks and custom git config
      • bypassing gitolite
      • gl-admin-push: bypassing gitolite for the gitolite-admin repo
      • disabling write access to take backups
    • INconvenience features
      • deleting a repo
      • renaming a repo
    • helping with gitweb
      • easier to link gitweb authorisation with gitolite
      • umask setting
    • advanced features
    • odds and ends
      • "poking" the admin repo to force a compile

---

user

• what users (not admins) need to know about gitolite
  • accessing gitolite
  • always available commands
  • digression: two kinds of repos
  • commands only available with "wildrepos" on
    • listing repos you created
    • set/get additional permissions for repos you created
    • adding a description to repos you created
  • "site-local" commands

---

virtualrefs-and-scoring

• virtual refs and scoring
  • real refs, virtual refs, and reftypes
    • side notes
      • who needs this?
      • number of refs returned
    • installing virtual refs
    • adding your own virtual refs
    • passing simple arguments to the VR script
  • scoring
  • documentation for individual virtual refs
    • VR_NAME

---

who-uses-it

• who uses gitolite

---

wildcard-repositories

• repositories named with wildcards
  • quick introduction
  • rc file setting required
  • examples of wildcard repos
    • wildcard repos with creator name in them
    • wildcard repos without creator name in them
  • valid regexes and how they are used
    • side-note: valid regexes
    • side-note: line-anchored regexes
      • contrast with refexes
  • handing out rights to wildcard-matched repos
    • (admin) adding other roles than READERS and WRITERS
      • IMPORTANT WARNING ABOUT THIS FEATURE
  • setting a gitweb description for a wildcard-matched repo
  • reporting
  • deleting a wild repo
  • how it actually works

---

gerrit

• comparing gerrit and gitolite

---

gitolite-tools

• gitolite-tools
  • Homepage

---

mirroring-complex-example

• semi-autonomous mirroring setup example
  • overview of problem
  • overview of setup
    • gitolite feature recap
  • pre-requisites
  • quick setup
  • step by step
    • (1) gitolite.conf
    • (2) master/sam.conf
    • (3) host admins only -- master/sam/p1.conf
    • (4) mirrors/sam/p1.conf
    • (5) slave/frodo/sam.conf
    • (6) manual sync
  • next steps
  • appendix A: delegation helper files

---

monkeysphere

• (contributed doc: integrating gitolite with monkeysphere)

---

putty

• putty and msysgit
  • msysgit setup
  • Going back to OpenSSH
  • Putty keys
    • Creating a new key
    • Importing an existing key
    • Loading an existing key
    • Public key
    • Putty ageant
  • Sessionless or raw hostname usage
  • Putty sessions
  • Host key authentication
  • Debugging multiple putty ageant keys
  • Setperms and other commands
  • About this document

---

hub

• the 'hub' ADC
  • a home grown 'hub' for git repos
  • general syntax
    • Bob's commands
    • Alice's "just looking" commands
    • Alice's "action" commands
  • what next?
  • note to the admin: configuration variables

---

README-adc

• brief descriptions of the shipped ADCs (admin-defined commands)

---

repo-deletion

• deleting repos safely

---

sskm

• changing keys -- self service key management
  • Important!
    • Key fingerprints
    • Active keys
    • Selecting which key to use
    • Public vs. private keys
  • Listing your existing keys
  • Adding or Replacing a key
    • Step 1: Adding the Key
    • Step 2: Confirming the addition
    • Optional: Undoing a mistaken add (before confirmation)
  • Removing a key
    • Step 1: Mark the key for deletion
    • Step 2: Confirming the deletion
    • Optional: Undoing a mistaken delete (before confirmation)
  • important notes for the admin

---

password-access

• password access to gitolite
  • problems
  • solution
  • some hints, notes and caveats
  • what the 2 scripts actually do
  • setting up password access

---

README-ldap

• ldap helper programs

---

README-vim

• Vim Syntax Highlight

---

README-t

• notes on the testing setup
  • terminology
  • notes and background
  • playing with gitolite
  • testing gitolite
  • instructions for adding new tests