shell doc: emphasize purpose and security model
The original git-shell(1) manpage emphasized that the shell supports only git transport commands. As the shell gained features, that emphasis and focus in the manual has been lost. Bring it back by splitting the manpage into a few short sections and fleshing out each: - SYNOPSIS, describing how the shell gets used in practice - DESCRIPTION, which gives an overview of the purpose and guarantees provided by this restricted shell - COMMANDS, listing supported commands and restrictions on the arguments they accept - INTERACTIVE USE, describing the interactive mode Also add a "see also" section with related reading. Signed-off-by: Jonathan Nieder <jrnieder@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jonathan Nieder committed
Mar 9, 2013 at 13:55 UTC
cdd9b3c96cc4a01bbc5f2f778e75028ea67a5f91
1 file changed
+49
-13
Documentation/git-shell.txt
+49
-13
@@ -9,25 +9,61 @@ git-shell - Restricted login shell for Git-only SSH access
9
SYNOPSIS
10
--------
11
[verse]
12
-'git shell' [-c <command> <argument>]
12
+'chsh' -s $(command -v git-shell) <user>
13
+'git clone' <user>`@localhost:/path/to/repo.git`
14
+'ssh' <user>`@localhost`
15
16
DESCRIPTION
17
-----------
18
17
-A login shell for SSH accounts to provide restricted Git access. When
18
-'-c' is given, the program executes <command> non-interactively;
19
-<command> can be one of 'git receive-pack', 'git upload-pack', 'git
20
-upload-archive', 'cvs server', or a command in COMMAND_DIR. The shell
21
-is started in interactive mode when no arguments are given; in this
22
-case, COMMAND_DIR must exist, and any of the executables in it can be
23
-invoked.
19
+This is a login shell for SSH accounts to provide restricted Git access.
20
+It permits execution only of server-side Git commands implementing the
21
+pull/push functionality, plus custom commands present in a subdirectory
22
+named `git-shell-commands` in the user's home directory.
23
25
-'cvs server' is a special command which executes git-cvsserver.
24
+COMMANDS
25
+--------
26
+
27
+'git shell' accepts the following commands after the '-c' option:
28
+
29
+'git receive-pack <argument>'::
30
+'git upload-pack <argument>'::
31
+'git upload-archive <argument>'::
32
+ Call the corresponding server-side command to support
33
+ the client's 'git push', 'git fetch', or 'git archive --remote'
34
+ request.
35
+'cvs server'::
36
+ Imitate a CVS server. See linkgit:git-cvsserver[1].
37
+
38
+If a `~/git-shell-commands` directory is present, 'git shell' will
39
+also handle other, custom commands by running
40
+"`git-shell-commands/<command> <arguments>`" from the user's home
41
+directory.
42
+
43
+INTERACTIVE USE
44
+---------------
45
27
-COMMAND_DIR is the path "$HOME/git-shell-commands". The user must have
28
-read and execute permissions to the directory in order to execute the
29
-programs in it. The programs are executed with a cwd of $HOME, and
30
-<argument> is parsed as a command-line string.
46
+By default, the commands above can be executed only with the '-c'
47
+option; the shell is not interactive.
48
+
49
+If a `~/git-shell-commands` directory is present, 'git shell'
50
+can also be run interactively (with no arguments). If a `help`
51
+command is present in the `git-shell-commands` directory, it is
52
+run to provide the user with an overview of allowed actions. Then a
53
+"git> " prompt is presented at which one can enter any of the
54
+commands from the `git-shell-commands` directory, or `exit` to close
55
+the connection.
56
+
57
+Generally this mode is used as an administrative interface to allow
58
+users to list repositories they have access to, create, delete, or
59
+rename repositories, or change repository descriptions and
60
+permissions.
61
+
62
+SEE ALSO
63
+--------
64
+ssh(1),
65
+linkgit:git-daemon[1],
66
+contrib/git-shell-commands/README
67
68
GIT
69
---