man1/git-shell.1

   1 '\" t
   2 .\"     Title: git-shell
   3 .\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
   5 .\"      Date: 2024-08-01
   6 .\"    Manual: Git Manual
   7 .\"    Source: Git 2.46.0.46.g406f326d27
   8 .\"  Language: English
   9 .\"
  10 .TH "GIT\-SHELL" "1" "2024-08-01" "Git 2\&.46\&.0\&.46\&.g406f326" "Git Manual"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 git-shell \- Restricted login shell for Git\-only SSH access
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 \fIchsh\fR \-s $(command \-v git\-shell) <user>
  36 \fIgit clone\fR <user>\fB@localhost:/path/to/repo\&.git\fR
  37 \fIssh\fR <user>\fB@localhost\fR
  38 .fi
  39 .SH "DESCRIPTION"
  40 .sp
  41 This is a login shell for SSH accounts to provide restricted Git access\&. It permits execution only of server\-side Git commands implementing the pull/push functionality, plus custom commands present in a subdirectory named \fBgit\-shell\-commands\fR in the user\(cqs home directory\&.
  42 .SH "COMMANDS"
  43 .sp
  44 \fIgit shell\fR accepts the following commands after the \fB\-c\fR option:
  45 .PP
  46 \fIgit receive\-pack <argument>\fR, \fIgit upload\-pack <argument>\fR, \fIgit upload\-archive <argument>\fR
  47 .RS 4
  48 Call the corresponding server\-side command to support the client\(cqs
  49 \fIgit push\fR,
  50 \fIgit fetch\fR, or
  51 \fIgit archive \-\-remote\fR
  52 request\&.
  53 .RE
  54 .PP
  55 \fIcvs server\fR
  56 .RS 4
  57 Imitate a CVS server\&. See
  58 \fBgit-cvsserver\fR(1)\&.
  59 .RE
  60 .sp
  61 If a \fB~/git\-shell\-commands\fR directory is present, \fIgit shell\fR will also handle other, custom commands by running "\fBgit\-shell\-commands/<command> <arguments>\fR" from the user\(cqs home directory\&.
  62 .SH "INTERACTIVE USE"
  63 .sp
  64 By default, the commands above can be executed only with the \fB\-c\fR option; the shell is not interactive\&.
  65 .sp
  66 If a \fB~/git\-shell\-commands\fR directory is present, \fIgit shell\fR can also be run interactively (with no arguments)\&. If a \fBhelp\fR command is present in the \fBgit\-shell\-commands\fR directory, it is run to provide the user with an overview of allowed actions\&. Then a "git> " prompt is presented at which one can enter any of the commands from the \fBgit\-shell\-commands\fR directory, or \fBexit\fR to close the connection\&.
  67 .sp
  68 Generally this mode is used as an administrative interface to allow users to list repositories they have access to, create, delete, or rename repositories, or change repository descriptions and permissions\&.
  69 .sp
  70 If a \fBno\-interactive\-login\fR command exists, then it is run and the interactive shell is aborted\&.
  71 .SH "EXAMPLES"
  72 .sp
  73 To disable interactive logins, displaying a greeting instead:
  74 .sp
  75 .if n \{\
  76 .RS 4
  77 .\}
  78 .nf
  79 $ chsh \-s /usr/bin/git\-shell
  80 $ mkdir $HOME/git\-shell\-commands
  81 $ cat >$HOME/git\-shell\-commands/no\-interactive\-login <<\eEOF
  82 #!/bin/sh
  83 printf \*(Aq%s\en\*(Aq "Hi $USER! You\*(Aqve successfully authenticated, but I do not"
  84 printf \*(Aq%s\en\*(Aq "provide interactive shell access\&."
  85 exit 128
  86 EOF
  87 $ chmod +x $HOME/git\-shell\-commands/no\-interactive\-login
  88 .fi
  89 .if n \{\
  90 .RE
  91 .\}
  92 .sp
  93 To enable git\-cvsserver access (which should generally have the \fBno\-interactive\-login\fR example above as a prerequisite, as creating the git\-shell\-commands directory allows interactive logins):
  94 .sp
  95 .if n \{\
  96 .RS 4
  97 .\}
  98 .nf
  99 $ cat >$HOME/git\-shell\-commands/cvs <<\eEOF
 100 if ! test $# = 1 && test "$1" = "server"
 101 then
 102         echo >&2 "git\-cvsserver only handles \e"server\e""
 103         exit 1
 104 fi
 105 exec git cvsserver server
 106 EOF
 107 $ chmod +x $HOME/git\-shell\-commands/cvs
 108 .fi
 109 .if n \{\
 110 .RE
 111 .\}
 112 .SH "SEE ALSO"
 113 .sp
 114 ssh(1), \fBgit-daemon\fR(1), contrib/git\-shell\-commands/README
 115 .SH "GIT"
 116 .sp
 117 Part of the \fBgit\fR(1) suite