git shell

Restricted shell for SSH-only Git accounts.

🎯 What & why

git shell is a restricted login shell that only speaks Git. Set it as the git user's login shell on a server so SSH keys can push/fetch but cannot get an interactive shell.

🧠 Mental model

Think of it as a tiny allow-list dispatcher: SSH hands it a command string, it accepts only git-upload-pack, git-receive-pack, git-upload-archive (plus anything you drop into git-shell-commands/), and rejects everything else.

🛠️ Synopsis

git-shell [-c <command>]

# /etc/passwd entry
git:x:1001:1001::/home/git:/usr/bin/git-shell

# ad-hoc allow-list
~git/git-shell-commands/<name>   # executable scripts callable by name
~git/git-shell-commands/no-interactive-login   # custom banner on bare ssh

🎚️ Switches & options

Flag	What it does
`-c <cmd>`	Run the given Git command string (this is what sshd passes in)
`(no args)`	Interactive mode; runs scripts from `git-shell-commands/` if present, else exits
`git-shell-commands/help`	Optional script listed when the user types `help`
`git-shell-commands/no-interactive-login`	If present, controls the message shown for bare ssh logins
`chsh -s /usr/bin/git-shell git`	⚠️ Activates the restriction for the `git` user — verify SSH still works first

💡 Use cases

Locking down a self-hosted Git server so the git user has no interactive shell
Foundation for gitolite/gitea-style setups that layer ACLs on top
Hosting bare repos accessible only via git@host:repo.git
Allowing a curated set of admin scripts (backup, repo-create) without granting a real shell

🧪 Examples

Add to /etc/shells then assign

echo /usr/bin/git-shell | sudo tee -a /etc/shells && sudo chsh -s /usr/bin/git-shell git

What sshd actually invokes

git-shell -c 'git-upload-pack /srv/git/repo.git'

Drop in an allow-listed admin script

sudo install -m 755 mkrepo.sh ~git/git-shell-commands/mkrepo

Test from a client against 127.0.0.1

ssh git@127.0.0.1 mkrepo new-project

🎓 Recommendations

Always test SSH key login with the new shell before logging out of root — a typo locks you out of the git account
Prefer gitolite or Gitea/Forgejo over hand-rolled git-shell for anything beyond a handful of repos
Keep git-shell-commands/ minimal and audited; every script there is effectively a privilege boundary

🪤 Common pitfalls

Forgetting to add /usr/bin/git-shell to /etc/shells — chsh will refuse on most distros
Assuming git-shell provides per-repo ACLs; it doesn't — it's all-or-nothing per Unix user
Leaving the git user with bash 'just for setup' and never switching back

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.