Git 中文文档

Soft Serve


Build Status

A tasty, self-hostable Git server for the command line. 🍦

Easy to navigate TUI available over SSH
Clone repos over SSH, HTTP, or Git protocol
Manage repos with SSH
Create repos on demand with SSH or git push
Browse repos, files and commits with SSH-accessible
Print files over SSH with or without syntax highlighting and line numbers
Easy access control with SSH
Allow/disallow anonymous access
Add collaborators with SSH public keys
Repos can be public or private

Where can I see it?


Just run ssh git.charm.sh for an example. You can also try some of the following commands:

  1. ``` shell
  2. # Jump directly to a repo in the TUI
  3. ssh git.charm.sh -t soft-serve

  5. # Print out a directory tree for a repo
  6. ssh git.charm.sh repo tree soft-serve

  8. # Print a specific file
  9. ssh git.charm.sh repo blob soft-serve cmd/soft/root.go

  11. # Print a file with syntax highlighting and line numbers
  12. ssh git.charm.sh repo blob soft-serve cmd/soft/root.go -c -l
  13. ```

Installation


Soft Serve is a single binary called soft. You can get it from a package manager:

  1. ``` shell
  2. # macOS or Linux
  3. brew tap charmbracelet/tap && brew install charmbracelet/tap/soft-serve

  5. # Arch Linux
  6. pacman -S soft-serve

  8. # Nix
  9. nix-env -iA nixpkgs.soft-serve

  11. # Debian/Ubuntu
  12. sudo mkdir -p /etc/apt/keyrings
  13. curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
  14. echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
  15. sudo apt update && sudo apt install soft-serve

  17. # Fedora/RHEL
  18. echo '[charm]
  19. name=Charm
  20. baseurl=https://repo.charm.sh/yum/
  21. enabled=1
  22. gpgcheck=1
  23. gpgkey=https://repo.charm.sh/yum/gpg.key' | sudo tee /etc/yum.repos.d/charm.repo
  24. sudo yum install soft-serve
  25. ```

You can also download a binary from the releases page. Packages are available in Alpine, Debian, and RPM formats. Binaries are available for Linux, macOS, and Windows.

Or just install it with go :

  1. ``` shell
  2. go install github.com/charmbracelet/soft-serve/cmd/soft@latest
  3. ```

A Docker image is also available.

Setting up a server


Make sure git is installed, then run soft serve. That’s it.

This will create a data directory that will store all the repos, ssh keys, and database.

To change the default data path use SOFT_SERVE_DATA_PATH environment variable.

  1. ``` shell
  2. SOFT_SERVE_DATA_PATH=/var/lib/soft-serve soft serve
  3. ```

When you run Soft Serve for the first time, make sure you have the SOFT_SERVE_INITIAL_ADMIN_KEYS environment variable is set to your ssh authorized key. Any added key to this variable will be treated as admin with full privileges.

Using this environment variable, Soft Serve will create a new admin user that has full privileges. You can rename and change the user settings later.

Server Settings


Once you start the server for the first time, the settings will be in config.yaml under your data directory. The default config.yaml is self-explanatory and will look like this:

  1. ``` yaml
  2. # Soft Serve Server configurations

  4. # The name of the server.
  5. # This is the name that will be displayed in the UI.
  6. name: "Soft Serve"

  8. # Log format to use. Valid values are "json", "logfmt", and "text".
  9. log_format: "text"

  11. # The SSH server configuration.
  12. ssh:
  13.   # The address on which the SSH server will listen.
  14.   listen_addr: ":23231"

  16.   # The public URL of the SSH server.
  17.   # This is the address that will be used to clone repositories.
  18.   public_url: "ssh://localhost:23231"

  20.   # The path to the SSH server's private key.
  21.   key_path: "ssh/soft_serve_host"

  23.   # The path to the SSH server's client private key.
  24.   # This key will be used to authenticate the server to make git requests to
  25.   # ssh remotes.
  26.   client_key_path: "ssh/soft_serve_client"

  28.   # The maximum number of seconds a connection can take.
  29.   # A value of 0 means no timeout.
  30.   max_timeout: 0

  32.   # The number of seconds a connection can be idle before it is closed.
  33.   idle_timeout: 120

  35. # The Git daemon configuration.
  36. git:
  37.   # The address on which the Git daemon will listen.
  38.   listen_addr: ":9418"

  40.   # The maximum number of seconds a connection can take.
  41.   # A value of 0 means no timeout.
  42.   max_timeout: 0

  44.   # The number of seconds a connection can be idle before it is closed.
  45.   idle_timeout: 3

  47.   # The maximum number of concurrent connections.
  48.   max_connections: 32

  50. # The HTTP server configuration.
  51. http:
  52.   # The address on which the HTTP server will listen.
  53.   listen_addr: ":23232"

  55.   # The path to the TLS private key.
  56.   tls_key_path: ""

  58.   # The path to the TLS certificate.
  59.   tls_cert_path: ""

  61.   # The public URL of the HTTP server.
  62.   # This is the address that will be used to clone repositories.
  63.   # Make sure to use https:// if you are using TLS.
  64.   public_url: "http://localhost:23232"

  66. # The stats server configuration.
  67. stats:
  68.   # The address on which the stats server will listen.
  69.   listen_addr: ":23233"

  71. # Additional admin keys.
  72. #initial_admin_keys:
  73. #  - "ssh-rsa AAAAB3NzaC1yc2..."

  75. ```

You can also use environment variables, to override these settings. All server settings environment variables start with SOFT_SERVE_ followed by the setting name all in uppercase. Here are some examples:

SOFT_SERVE_NAME : The name of the server that will appear in the TUI
SOFT_SERVE_SSH_LISTEN_ADDR : SSH listen address
SOFT_SERVE_SSH_KEY_PATH : SSH host key-pair path
SOFT_SERVE_HTTP_LISTEN_ADDR : HTTP listen address
SOFT_SERVE_HTTP_PUBLIC_URL : HTTP public URL used for cloning
SOFT_SERVE_GIT_MAX_CONNECTIONS : The number of simultaneous connections to git daemon

Configuration


Configuring Soft Serve is simple and straightforward. Use the SSH command-line interface to manage access settings, users, and repos.

Try ssh localhost -i ~/.ssh/id_ed25519 -p 23231 help for more info. Make sure you use your key here.

For ease of use, instead of specifying the key, port, and hostname every time you SSH into Soft Serve, add your own Soft Serve instance entry to your SSH config. For instance, to use ssh soft instead of typing `ssh localhost -i /.ssh/id_ed25519 -p 23231, we can define a soft entry in our SSH config file /.ssh/config`.

  1. ``` sh
  2. Host soft
  3.   HostName localhost
  4.   Port 23231
  5.   IdentityFile ~/.ssh/id_ed25519

  7. ```

Now, we can do ssh soft to SSH into Soft Serve. Since git is also aware of this config, you can use soft as the hostname for your clone commands.

  1. ``` shell
  2. git clone ssh://soft/dotfiles
  3. # make changes
  4. # add & commit
  5. git push origin main
  6. ```

NoteThe -i part will be omitted in the examples below for brevity. You can add your server settings to your sshconfig for quicker access.


Access Levels


Soft Serve offers a simple access control. There are four access levels, no-access, read-only, read-write, and admin-access.

admin-access has full control of the server and can make changes to users and repos.

read-write access gets full control of repos.

read-only can read public repos.

no-access denies access to all repos.

Authentication


Everything that needs authentication is done using SSH. Make sure you have added an entry for your Soft Serve instance in your ~/.ssh/config file.

By default, Soft Serve gives ready-only permission to anonymous connections to any of the above protocols. This is controlled by two settings anon-access and allow-keyless.

anon-access : Defines the access level for anonymous users. Available options are no-access, read-only, read-write, and admin-access. Default is read-only.
allow-keyless : Whether to allow connections that doesn't use keys to pass. Setting this to false would disable access to SSH keyboard-interactive, HTTP, and Git protocol connections. Default is true.

  1. ``` shell
  2. $ ssh -p 23231 localhost settings
  3. Manage server settings

  5. Usage:
  6.   ssh -p 23231 localhost settings [command]

  8. Available Commands:
  9.   allow-keyless Set or get allow keyless access to repositories
  10.   anon-access   Set or get the default access level for anonymous users

  12. Flags:
  13.   -h, --help   help for settings

  15. Use "ssh -p 23231 localhost settings [command] --help" for more information about a command.
  16. ```

NoteThese settings can only be changed by admins.


When allow-keyless is disabled, connections that don't use SSH Public Key authentication will get denied. This means cloning repos over HTTP(s) or git:// will get denied.

Meanwhile, anon-access controls the access level granted to connections that use SSH Public Key authentication but are not registered users. The default setting for this is read-only. This will grant anonymous connections that use SSH Public Key authentication read-only access to public repos.

anon-access is also used in combination with allow-keyless to determine the access level for HTTP(s) and git:// clone requests.

Authorization


Admins can manage users and their keys using the user command. Once a user is created and has access to the server, they can manage their own keys and settings.

To create a new user simply use user create :

  1. ``` shell
  2. # Create a new user
  3. ssh -p 23231 localhost user create beatrice

  5. # Add user keys
  6. ssh -p 23231 localhost user add-pubkey beatrice ssh-rsa AAAAB3Nz...
  7. ssh -p 23231 localhost user add-pubkey beatrice ssh-ed25519 AAAA...

  9. # Create another user with public key
  10. ssh -p 23231 localhost user create frankie '-k "ssh-ed25519 AAAATzN..."'

  12. # Need help?
  13. ssh -p 23231 localhost user help
  14. ```

Once a user is created, they get read-only access to public repositories. They can also create new repositories on the server.

Users can manage their keys using the pubkey command:

  1. ``` shell
  2. # List user keys
  3. ssh -p 23231 localhost pubkey list

  5. # Add key
  6. ssh -p 23231 localhost pubkey add ssh-ed25519 AAAA...

  8. # Wanna change your username?
  9. ssh -p 23231 localhost set-username yolo

  11. # To display user info
  12. ssh -p 23231 localhost info
  13. ```

Repositories


You can manage repositories using the repo command.

  1. ``` shell
  2. # Run repo help
  3. $ ssh -p 23231 localhost repo help
  4. Manage repositories

  6. Usage:
  7.   ssh -p 23231 localhost repo [command]

  9. Aliases:
  10.   repo, repos, repository, repositories

  12. Available Commands:
  13.   blob         Print out the contents of file at path
  14.   branch       Manage repository branches
  15.   collab       Manage collaborators
  16.   create       Create a new repository
  17.   delete       Delete a repository
  18.   description  Set or get the description for a repository
  19.   hide         Hide or unhide a repository
  20.   import       Import a new repository from remote
  21.   info         Get information about a repository
  22.   is-mirror    Whether a repository is a mirror
  23.   list         List repositories
  24.   private      Set or get a repository private property
  25.   project-name Set or get the project name for a repository
  26.   rename       Rename an existing repository
  27.   tag          Manage repository tags
  28.   tree         Print repository tree at path

  30. Flags:
  31.   -h, --help   help for repo

  33. Use "ssh -p 23231 localhost repo [command] --help" for more information about a command.
  34. ```

To use any of the above repo commands, a user must be a collaborator in the repository. More on this below.

Creating Repositories


To create a repository, first make sure you are a registered user. Use the repo create <repo> command to create a new repository:

  1. ``` shell
  2. # Create a new repository
  3. ssh -p 23231 localhost repo create icecream

  5. # Create a repo with description
  6. ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"'

  8. # ... and project name
  9. ssh -p 23231 localhost repo create icecream '-d "This is an Ice Cream description"' '-n "Ice Cream"'

  11. # I need my repository private!
  12. ssh -p 23231 localhost repo create icecream -p '-d "This is an Ice Cream description"' '-n "Ice Cream"'

  14. # Help?
  15. ssh -p 23231 localhost repo create -h
  16. ```

Or you can add your Soft Serve server as a remote to any existing repo, given you have write access, and push to remote:

  1. ``` sh
  2. git remote add origin ssh://localhost:23231/icecream

  4. ```

After you’ve added the remote just go ahead and push. If the repo doesn’t exist on the server it’ll be created.

  1. ``` sh
  2. git push origin main

  4. ```

Repositories can be nested too:

  1. ``` shell
  2. # Create a new nested repository
  3. ssh -p 23231 localhost repo create charmbracelet/icecream

  5. # Or ...
  6. git remote add charm ssh://localhost:23231/charmbracelet/icecream
  7. git push charm main
  8. ```

Deleting Repositories


You can delete repositories using the repo delete <repo> command.

  1. ``` shell
  2. ssh -p 23231 localhost repo delete icecream
  3. ```

Renaming Repositories


Use the repo rename <old> <new> command to rename existing repositories.

  1. ``` shell
  2. ssh -p 23231 localhost repo rename icecream vanilla
  3. ```

Repository Collaborators


Sometimes you want to restrict write access to certain repositories. This can be achieved by adding a collaborator to your repository.

Use the repo collab <command> <repo> command to manage repo collaborators.

  1. ``` shell
  2. # Add collaborator to soft-serve
  3. ssh -p 23231 localhost repo collab add soft-serve frankie

  5. # Remove collaborator
  6. ssh -p 23231 localhost repo collab remove soft-serve beatrice

  8. # List collaborators
  9. ssh -p 23231 localhost repo collab list soft-serve
  10. ```

Repository metadata


You can also change the repo's description, project name, whether it's private, etc using the repo <command> command.

  1. ``` shell
  2. # Set description for repo
  3. ssh -p 23231 localhost repo description icecream "This is a new description"

  5. # Hide repo from listing
  6. ssh -p 23231 localhost repo hidden icecream true

  8. # List repository info (branches, tags, description, etc)
  9. ssh -p 23231 localhost repo icecream info
  10. ```

To make a repository private, use repo private <repo> [true|false]. Private repos can only be accessed by admins and collaborators.

  1. ``` shell
  2. ssh -p 23231 localhost repo icecream private true
  3. ```

Repository Branches & Tags


Use repo branch and repo tag to list, and delete branches or tags. You can also use repo branch default to set or get the repository default branch.

Repository Tree


To print a file tree for the project, just use the repo tree command along with the repo name as the SSH command to your Soft Serve server:

  1. ``` shell
  2. ssh -p 23231 localhost repo tree soft-serve
  3. ```

You can also specify the sub-path and a specific reference or branch.

  1. ``` shell
  2. ssh -p 23231 localhost repo tree soft-serve server/config
  3. ssh -p 23231 localhost repo tree soft-serve main server/config
  4. ```

From there, you can print individual files using the repo blob command:

  1. ``` shell
  2. ssh -p 23231 localhost repo blob soft-serve cmd/soft/root.go
  3. ```

You can add the -c flag to enable syntax coloring and -l to print line numbers:

  1. ``` shell
  2. ssh -p 23231 localhost repo blob soft-serve cmd/soft/root.go -c -l

  4. ```

Use --raw to print raw file contents. This is