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