mugit @ 75fc9d1

A README.md

@@ -0,0 +1,140 @@
+# mugit
+
+A lightweight, self-hosted Git server that your cow will love.
+
+[See it in action!](https://git.olexsmir.xyz)
+
+## Features
+
+- Web interface — browse repositories, view commits, files, and diffs
+- Git Smart HTTP — clone over HTTPS (use SSH for pushing)
+- Git over SSH — push and clone over SSH
+- Mirroring — automatically mirror repositories (supports GitHub authentication)
+- Private repositories — repos accessible only via SSH
+- CLI — command-line for managing your repositories
+
+## Quick install & deploy
+
+```sh
+git clone https://git.olexsmir.xyz/mugit.git
+cd mugit
+go build
+
+# or
+go install github.com/olexsmir/mugit@latest
+```
+
+For nixos you can use our flake, see [my config](https://git.olexsmir.xyz/dotfiles/blob/master/nix/modules/mugit.nix) for reference.
+
+Start the server:
+
+```sh
+# start server with default config lookup
+mugit serve
+
+# start with a custom config path
+mugit -c /path/to/config.yaml serve
+```
+
+
+## Configuration
+
+mugit uses YAML for configuration. By default the server looks for a configuration file in this order (override with `-c` / `--config`):
+1. `./config.yaml`
+2. `/etc/mugit.yaml`
+3. `/var/lib/mugit/config.yaml`
+
+
+Durations follow Go's duration syntax (examples: `1h`, `30m`, `5s`). See: https://pkg.go.dev/time#ParseDuration
+
+Minimal configuration example:
+
+```yaml
+meta:
+  host: git.olexsmir.xyz
+
+repo:
+  dir: /var/lib/mugit
+```
+
+Full example:
+
+```yaml
+server:
+  host: 0.0.0.0 # bind address (0.0.0.0 = all interfaces)
+  port: 5555    # HTTP port (defaults to 8080 when omitted)
+
+meta:
+  title: "My Git Server"    # site title shown on index page
+  description: "A place for my projects"
+  host: git.example.com     # used for clone URLs and go-import meta tag
+
+repo:
+  dir: /var/lib/mugit   # directory with repositories
+  # Default README filenames (applied when omitted):
+  readmes:
+    - README.md
+    - readme.md
+    - README.html
+    - readme.html
+    - README.txt
+    - readme.txt
+    - readme
+  # Default branch names considered the repository 'master' (applied when omitted):
+  masters:
+    - master
+    - main
+
+# ssh: push/clone over SSH
+ssh:
+  enable: true
+  port: 2222  # SSH port (default 2222)
+  host_key: /var/lib/mugit/host   # path to SSH host key (generate with ssh-keygen)
+  # Only these public keys can access private repos and push to others.
+  keys:
+    - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA......
+    - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA......
+
+# mirror: automatic mirrors of external repositories
+mirror:
+  enable: true
+  interval: 1h  # sync frequency
+  # Tokens can be provided directly, or read from environment/file:
+  # - literal: "ghp_xxxxxxxxxxxx"
+  # - from env: "${env:GITHUB_TOKEN}" (will read $GITHUB_TOKEN)
+  # - from file: "${file:/abs/path/to/token.txt}"
+  github_token: "${env:GITHUB_TOKEN}"
+
+cache:
+  home_page: 5m   # cache index/home page
+  readme: 1m      # cache rendered README per repo
+  diff: 15m       # cache computed diffs
+```
+
+## CLI
+
+```sh
+# start server
+mugit serve
+
+# create new public repository
+mugit repo new myproject
+
+# create new private repository
+mugit repo new --private myproject
+
+# create a mirror of an external repository
+mugit repo new myproject --mirror https://codeberg.org/user/repo
+mugit repo new myproject --private --mirror https://github.com/user/repo
+
+# toggle repository visibility
+mugit repo private myproject
+
+# show and set repository description
+mugit repo description myproject
+mugit repo description myproject "My awesome project"
+```
+
+## License
+
+mugit is licensed under the MIT License.

D

@@ -1,103 +0,0 @@
-mugit
------
-
-A cgit/gitweb-like server that your cow will love.
-
-FEATURES
-- Web interface - browse repositories, view commits, files, and diffs
-- Git Smart HTTP - clone over https (use ssh for pushing)
-- Git over SSH - push and clone over ssh
-- Private repositories - repositories that are only accessible via ssh
-- Mirroring - Automatically mirror repositories (supports github auth)
-- CLI - for managing your repos
-
-INSTALL
-
-Clone it, `go build` it.
-
-You can also you nix flake if you're on nixos.
-
-CONFIG
-
-Uses yaml for configuration, look for a 'config.yaml' in:
-1. `/var/lib/mugit/config.yaml`
-2. `$XDG_CONFIG_HOME/mugit/config.yaml` (or `~/.config/mugit/config.yaml`)
-3. `/etc/mugit/config.yaml`
-
-Pass `--config` flag to point it elsewhere
-
-Example config:
-
-    server:
-      host: 0.0.0.0
-      port: 5555
-
-    meta:
-      # title and description you see on the index page
-      title: My Git Server
-      description: A place for my projects
-      # used for clone urls and go-import meta tag
-      host: git.example.com
-
-    repo:
-      # where all your repo live (maybe die too). mugit doesn't traverse subdirs
-      dir: /var/lib/mugit
-      # readme files to look for
-      readmes:
-        - README.md
-        - readme.md
-      # master branches name to look for
-      masters:
-        - main
-        - master
-
-    ssh:
-      enable: true
-      port: 2222
-      # path to ssh private key for ssh server to use
-      # you can generate it with: ssh-keygen -f key/path
-      host_key: /var/lib/mugit/ssh_host_key
-      # list of keys that are allowed to access private repos
-      keys:
-        - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPLLJdkVYKZgsayw+sHanKPKZbI0RMS2CakqBCEi5Trz
-        - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIMPQ0Qz0DFB+rGrD8ScUqbUTZ1/O8FHrOBF5bIAGQgMj 
-
-    mirror:
-      enable: true
-      # with which interval sync repo
-      interval: 1h
-      # github token for avoiding github rate limiting
-      github_token: "ghp_xxxxxxxxxxxx"
-
-
-CLI
-
-    # start server
-    mugit serve
-
-    # run with custom config
-    mugit -c /path/to/config.yml serve
-
-    # create new repository
-    mugit repo new myproject
-
-    # create new private repository
-    mugit repo new --private myproject
-
-    # create new mirror
-    mugit repo new myproject --mirror https://github.com/user/repo
-    mugit repo new myproject --mirror https://codeberg.org/user/repo
-
-    # toggle repository private status
-    mugit repo private myproject
-
-    # get repository description
-    mugit repo description myproject
-
-    # set new description
-    mugit repo description myproject "My awesome project"
-
-
-LICENSE
-
-mugit is licensed under MIT.