NameDateSize

..16-Mar-201612 KiB

CHANGELOG10-Nov-20158.7 KiB

check-g2-compat10-Nov-20153.6 KiB

contrib/10-Nov-20154 KiB

CONTRIBUTING10-Nov-20151.3 KiB

convert-gitosis-conf10-Nov-20153.6 KiB

COPYING10-Nov-201514.8 KiB

install10-Nov-20152.4 KiB

README.markdown10-Nov-20157.2 KiB

src/10-Nov-20154 KiB

t/30-Nov-20154 KiB

README.markdown

1Gitolite README
2===============
3
4## about this README
5
6**(Github-users: click the "wiki" link before sending me anything via github.)**
7
8**This is a minimal README for gitolite**, so you can quickly get started with:
9
10*   installing gitolite on a fresh userid on a Unix(-like) machine
11*   learning enough to do some basic access control
12
13**For anything more, you need to look at the complete documentation, at:
14<http://gitolite.com/gitolite>**.  Please go there for what/why/how, concepts,
15background, troubleshooting, more details on what is covered here, advanced
16features not covered here, migration from older gitolite, and many more
17topics.
18
19<!-- --------------------------------------------------------------------- -->
20
21## Assumptions
22
23*   You are familiar with:
24    *   OS: at least one Unix-like OS
25    *   ssh: ssh, ssh keys, ssh authorized keys file
26    *   git: basic use of git, bare and non-bare remotes
27
28*   You are setting up a fresh, ssh-based, installation of gitolite on a Unix
29    machine of some sort.
30
31*   You have root access, or someone has created a userid called "git" for you
32    to use and given you a password for it.  This is a brand new userid (or
33    you have deleted everything but `.bashrc` and similar files to make it
34    look like one!)
35
36*   If your server is not connected to the internet, you know how to clone the
37    gitolite source code by using some in-between server or "git bundle".
38
39<!-- --------------------------------------------------------------------- -->
40
41## Installation and setup
42
43### server requirements
44
45*   any unix system
46*   sh
47*   git 1.6.6 or later
48*   perl 5.8.8 or later
49*   openssh 5.0 or later
50*   a dedicated userid to host the repos (in this document, we assume it is
51    "git", but it can be anything; substitute accordingly)
52*   this user id does NOT currently have any ssh pubkey-based access
53    *   ideally, this user id has shell access ONLY by "su - git" from some
54        other userid on the same server (this ensure minimal confusion for ssh
55        newbies!)
56
57### steps to install
58
59First, prepare the ssh key:
60
61*   login to "git" on the server
62*   make sure `~/.ssh/authorized_keys` is empty or non-existent
63*   make sure your ssh public key from your workstation has been copied as
64    $HOME/YourName.pub
65
66Next, install gitolite by running these commands:
67
68    git clone git://github.com/sitaramc/gitolite
69    mkdir -p $HOME/bin
70    gitolite/install -to $HOME/bin
71
72Finally, setup gitolite with yourself as the administrator:
73
74    gitolite setup -pk YourName.pub
75
76If the last command doesn't run perhaps "bin" is not in your "PATH". You can
77either add it, or just run:
78
79    $HOME/bin/gitolite setup -pk YourName.pub
80
81If you get any other errors please refer to the online documentation whose URL
82was given at the top of this file.
83
84## adding users and repos
85
86*Do NOT add new repos or users manually on the server.*  Gitolite users,
87repos, and access rules are maintained by making changes to a special repo
88called "gitolite-admin" and *pushing* those changes to the server.
89
90To administer your gitolite installation, start by doing this on your
91workstation (if you have not already done so):
92
93    git clone git@host:gitolite-admin
94
95>   -------------------------------------------------------------------------
96
97>   **NOTE: if you are asked for a password, something went wrong.**.  Go hit
98>   the link for the complete documentation earlier in this file.
99
100>   -------------------------------------------------------------------------
101
102Now if you "cd gitolite-admin", you will see two subdirectories in it: "conf"
103and "keydir".
104
105To add new users alice, bob, and carol, obtain their public keys and add them
106to "keydir" as alice.pub, bob.pub, and carol.pub respectively.
107
108To add a new repo "foo" and give different levels of access to these
109users, edit the file "conf/gitolite.conf" and add lines like this:
110
111    repo foo
112        RW+         =   alice
113        RW          =   bob
114        R           =   carol
115
116Once you have made these changes, do something like this:
117
118    git add conf
119    git add keydir
120    git commit -m "added foo, gave access to alice, bob, carol"
121    git push
122
123When the push completes, gitolite will add the new users to
124`~/.ssh/authorized_keys` on the server, as well as create a new, empty, repo
125called "foo".
126
127## help for your users
128
129Once a user has sent you their public key and you have added them as
130specified above and given them access, you have to tell them what URL to
131access their repos at.  This is usually "git clone git@host:reponame"; see
132man git-clone for other forms.
133
134**NOTE**: again, if they are asked for a password, something is wrong.
135
136If they need to know what repos they have access to, they just have to run
137"ssh git@host info".
138
139## access rule examples
140
141Gitolite's access rules are very powerful.  The simplest use was already
142shown above.  Here is a slightly more detailed example:
143
144    repo foo
145        RW+                     =   alice
146        -   master              =   bob
147        -   refs/tags/v[0-9]    =   bob
148        RW                      =   bob
149        RW  refs/tags/v[0-9]    =   carol
150        R                       =   dave
151
152Here's what these example rules say:
153
154  * alice can do anything to any branch or tag -- create, push,
155    delete, rewind/overwrite etc.
156
157  * bob can create or fast-forward push any branch whose name does
158    not start with "master" and create any tag whose name does not
159    start with "v"+digit.
160
161  * carol can create tags whose names start with "v"+digit.
162
163  * dave can clone/fetch.
164
165Please see the main documentation linked above for all the gory details, as
166well as more features and examples.
167
168## groups
169
170Gitolite allows you to group users or repos for convenience.  Here's an
171example that creates two groups of users:
172
173    @staff      =   alice bob carol
174    @interns    =   ashok
175
176    repo secret
177        RW      =   @staff
178
179    repo foss
180        RW+     =   @staff
181        RW      =   @interns
182
183Group lists accumulate.  The following two lines have the same effect as
184the earlier definition of @staff above:
185
186    @staff      =   alice bob
187    @staff      =   carol
188
189You can also use group names in other group names:
190
191    @all-devs   =   @staff @interns
192
193Finally, @all is a special group name that is often convenient to use if
194you really mean "all repos" or "all users".
195
196## commands
197
198Users can run certain commands remotely, using ssh.  Running
199
200    ssh git@host help
201
202prints a list of available commands.
203
204The most commonly used command is "info".  All commands respond to a
205single argument of "-h" with suitable information.
206
207If you have shell on the server, you have a lot more commands available to
208you; try running "gitolite help".
209
210<!-- --------------------------------------------------------------------- -->
211
212## LICENSE
213
214# contact and support
215
216Please see <http://gitolite.com/gitolite/#contact> for mailing list and IRC
217info.
218
219# license
220
221The gitolite software is copyright Sitaram Chamarty and is licensed under the
222GPL v2; please see the file called COPYING in the source distribution.
223
224Please see <http://gitolite.com/gitolite/#license> for more.
225
226>   -------------------------------------------------------------------------
227
228>   **NOTE**: GIT is a trademark of Software Freedom Conservancy and my use of
229>   "Gitolite" is under license.
230
231>   -------------------------------------------------------------------------
232