Add test case for basic commit functionality.
[git/git.git] / Documentation / git-daemon.txt
CommitLineData
7fc9d69f
JH
1git-daemon(1)
2=============
3
4NAME
5----
7bd7f280 6git-daemon - A really simple server for git repositories
7fc9d69f
JH
7
8SYNOPSIS
9--------
353ce815 10[verse]
dd467629 11'git-daemon' [--verbose] [--syslog] [--export-all]
b21c31c9 12 [--timeout=n] [--init-timeout=n] [--strict-paths]
603968d2 13 [--base-path=path] [--user-path | --user-path=path]
49ba83fb 14 [--interpolated-path=pathtemplate]
dd467629 15 [--reuseaddr] [--detach] [--pid-file=file]
355f5412
JH
16 [--enable=service] [--disable=service]
17 [--allow-override=service] [--forbid-override=service]
dd467629
JL
18 [--inetd | [--listen=host_or_ipaddr] [--port=n] [--user=user [--group=group]]
19 [directory...]
7fc9d69f
JH
20
21DESCRIPTION
22-----------
62cd033d 23A really simple TCP git daemon that normally listens on port "DEFAULT_GIT_PORT"
355f5412
JH
24aka 9418. It waits for a connection asking for a service, and will serve
25that service if it is enabled.
7fc9d69f 26
62cd033d
LAS
27It verifies that the directory has the magic file "git-daemon-export-ok", and
28it will refuse to export any git directory that hasn't explicitly been marked
2707da9c
PB
29for export this way (unless the '--export-all' parameter is specified). If you
30pass some directory paths as 'git-daemon' arguments, you can further restrict
31the offers to a whitelist comprising of those.
62cd033d 32
355f5412
JH
33By default, only `upload-pack` service is enabled, which serves
34`git-fetch-pack` and `git-peek-remote` clients that are invoked
35from `git-fetch`, `git-ls-remote`, and `git-clone`.
36
37This is ideally suited for read-only updates, i.e., pulling from
38git repositories.
7fc9d69f 39
e2b1d1cc
CC
40An `upload-archive` also exists to serve `git-archive`.
41
7fc9d69f
JH
42OPTIONS
43-------
ce335fe0 44--strict-paths::
4dbd1352
AE
45 Match paths exactly (i.e. don't allow "/foo/repo" when the real path is
46 "/foo/repo.git" or "/foo/repo/.git") and don't do user-relative paths.
47 git-daemon will refuse to start when this option is enabled and no
48 whitelist is specified.
49
b21c31c9
PB
50--base-path::
51 Remap all the path requests as relative to the given path.
52 This is sort of "GIT root" - if you run git-daemon with
53 '--base-path=/srv/git' on example.com, then if you later try to pull
54 'git://example.com/hello.git', `git-daemon` will interpret the path
603968d2 55 as '/srv/git/hello.git'.
b21c31c9 56
49ba83fb
JL
57--interpolated-path=pathtemplate::
58 To support virtual hosting, an interpolated path template can be
59 used to dynamically construct alternate paths. The template
dd467629
JL
60 supports %H for the target hostname as supplied by the client but
61 converted to all lowercase, %CH for the canonical hostname,
62 %IP for the server's IP address, %P for the port number,
49ba83fb 63 and %D for the absolute path of the named repository.
dd467629
JL
64 After interpolation, the path is validated against the directory
65 whitelist.
49ba83fb 66
2707da9c
PB
67--export-all::
68 Allow pulling from all directories that look like GIT repositories
4dbd1352 69 (have the 'objects' and 'refs' subdirectories), even if they
2707da9c
PB
70 do not have the 'git-daemon-export-ok' file.
71
62cd033d 72--inetd::
bce8230d 73 Have the server run as an inetd service. Implies --syslog.
dd467629
JL
74 Incompatible with --port, --listen, --user and --group options.
75
76--listen=host_or_ipaddr::
77 Listen on an a specific IP address or hostname. IP addresses can
78 be either an IPv4 address or an IPV6 address if supported. If IPv6
79 is not supported, then --listen=hostname is also not supported and
80 --listen must be given an IPv4 address.
81 Incompatible with '--inetd' option.
7fc9d69f 82
dd467629
JL
83--port=n::
84 Listen on an alternative port. Incompatible with '--inetd' option.
7fc9d69f 85
2707da9c
PB
86--init-timeout::
87 Timeout between the moment the connection is established and the
88 client request is received (typically a rather low value, since
89 that should be basically immediate).
90
91--timeout::
92 Timeout for specific client sub-requests. This includes the time
93 it takes for the server to process the sub-request and time spent
94 waiting for next client's request.
95
9048fe1c
PB
96--syslog::
97 Log to syslog instead of stderr. Note that this option does not imply
98 --verbose, thus by default only error conditions will be logged.
99
603968d2
JH
100--user-path, --user-path=path::
101 Allow ~user notation to be used in requests. When
102 specified with no parameter, requests to
103 git://host/~alice/foo is taken as a request to access
104 'foo' repository in the home directory of user `alice`.
105 If `--user-path=path` is specified, the same request is
106 taken as a request to access `path/foo` repository in
107 the home directory of user `alice`.
108
b5cf3c8b
PB
109--verbose::
110 Log details about the incoming connections and requested files.
111
6c35119a
ML
112--reuseaddr::
113 Use SO_REUSEADDR when binding the listening socket.
114 This allows the server to restart without waiting for
115 old connections to time out.
116
117--detach::
118 Detach from the shell. Implies --syslog.
119
120--pid-file=file::
121 Save the process id in 'file'.
122
678dac6b
TS
123--user=user, --group=group::
124 Change daemon's uid and gid before entering the service loop.
125 When only `--user` is given without `--group`, the
126 primary group ID for the user is used. The values of
127 the option are given to `getpwnam(3)` and `getgrnam(3)`
128 and numeric IDs are not supported.
129+
130Giving these options is an error when used with `--inetd`; use
131the facility of inet daemon to achieve the same before spawning
132`git-daemon` if needed.
133
eda95d99 134--enable=service, --disable=service::
355f5412
JH
135 Enable/disable the service site-wide per default. Note
136 that a service disabled site-wide can still be enabled
137 per repository if it is marked overridable and the
138 repository enables the service with an configuration
139 item.
140
eda95d99 141--allow-override=service, --forbid-override=service::
355f5412
JH
142 Allow/forbid overriding the site-wide default with per
143 repository configuration. By default, all the services
144 are overridable.
145
4dbd1352
AE
146<directory>::
147 A directory to add to the whitelist of allowed directories. Unless
148 --strict-paths is specified this will also include subdirectories
149 of each named directory.
150
355f5412
JH
151SERVICES
152--------
153
154upload-pack::
155 This serves `git-fetch-pack` and `git-peek-remote`
156 clients. It is enabled by default, but a repository can
157 disable it by setting `daemon.uploadpack` configuration
158 item to `false`.
159
e2b1d1cc
CC
160upload-archive::
161 This serves `git-archive --remote`.
162
49ba83fb
JL
163EXAMPLES
164--------
f8a5da6d
CC
165We assume the following in /etc/services::
166+
167------------
168$ grep 9418 /etc/services
169git 9418/tcp # Git Version Control System
170------------
171
49ba83fb
JL
172git-daemon as inetd server::
173 To set up `git-daemon` as an inetd service that handles any
174 repository under the whitelisted set of directories, /pub/foo
175 and /pub/bar, place an entry like the following into
176 /etc/inetd all on one line:
177+
178------------------------------------------------
179 git stream tcp nowait nobody /usr/bin/git-daemon
d9c04ba3 180 git-daemon --inetd --verbose --export-all
49ba83fb
JL
181 /pub/foo /pub/bar
182------------------------------------------------
183
184
185git-daemon as inetd server for virtual hosts::
186 To set up `git-daemon` as an inetd service that handles
187 repositories for different virtual hosts, `www.example.com`
188 and `www.example.org`, place an entry like the following into
189 `/etc/inetd` all on one line:
190+
191------------------------------------------------
192 git stream tcp nowait nobody /usr/bin/git-daemon
d9c04ba3 193 git-daemon --inetd --verbose --export-all
49ba83fb
JL
194 --interpolated-path=/pub/%H%D
195 /pub/www.example.org/software
196 /pub/www.example.com/software
197 /software
198------------------------------------------------
199+
200In this example, the root-level directory `/pub` will contain
201a subdirectory for each virtual host name supported.
202Further, both hosts advertise repositories simply as
203`git://www.example.com/software/repo.git`. For pre-1.4.0
204clients, a symlink from `/software` into the appropriate
205default repository could be made as well.
206
207
dd467629
JL
208git-daemon as regular daemon for virtual hosts::
209 To set up `git-daemon` as a regular, non-inetd service that
210 handles repositories for multiple virtual hosts based on
211 their IP addresses, start the daemon like this:
212+
213------------------------------------------------
214 git-daemon --verbose --export-all
215 --interpolated-path=/pub/%IP/%D
216 /pub/192.168.1.200/software
217 /pub/10.10.220.23/software
218------------------------------------------------
219+
220In this example, the root-level directory `/pub` will contain
221a subdirectory for each virtual host IP address supported.
222Repositories can still be accessed by hostname though, assuming
223they correspond to these IP addresses.
224
225
7fc9d69f
JH
226Author
227------
4dbd1352
AE
228Written by Linus Torvalds <torvalds@osdl.org>, YOSHIFUJI Hideaki
229<yoshfuji@linux-ipv6.org> and the git-list <git@vger.kernel.org>
7fc9d69f
JH
230
231Documentation
232--------------
233Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
234
235GIT
236---
a7154e91 237Part of the gitlink:git[7] suite