11# AGENTS.md file for smolgit
22
33## Overview
4+
45smolgit is a minimalist Git server written in Go with a React/TS frontend. It exposes a REST API over HTTP and an SSH interface.
56
67## Directory layout
8+
79- ` cmd/ ` – main entry point.
810- ` pkg/ ` – core libraries: ssh, git, config, model, route, etc.
911- ` frontend/ ` – React/TS UI, built into ` dist/ ` and embedded via ` go:embed ` .
@@ -13,22 +15,23 @@ smolgit is a minimalist Git server written in Go with a React/TS frontend. It ex
1315
1416## Build & Run
1517
16- | Target | Description | Command |
17- | --------| -------------| ---------|
18- | ` build ` | Compile Go binary into ` bin/smolgit ` | ` make build ` |
19- | ` build-frontend ` | Build React assets into ` dist/ ` | ` make build-frontend ` |
20- | ` build-docker ` | Build Docker image | ` make build-docker ` |
21- | ` run ` | Run compiled binary locally | ` make run ` |
22- | ` run-docker ` | Run smolgit in a container | ` make run-docker ` |
23- | ` config ` | Generate default config to stdout | ` make config ` |
24- | ` config-docker ` | Generate config for Docker | ` make config-docker ` |
25- | ` clean ` | Remove build artifacts | ` make clean ` |
26- | ` lint ` | Run golangci-lint on Go code | ` make lint ` |
27- | ` test ` | Run Go unit tests | ` make test ` |
28- | ` integration-test ` | Run Bats integration tests | ` make integration-test ` |
29- | ` help ` | Show available make targets | ` make help ` |
18+ | Target | Description | Command |
19+ | ------------------ | ------------------------------------ | ----------------------- |
20+ | ` build ` | Compile Go binary into ` bin/smolgit ` | ` make build ` |
21+ | ` build-frontend ` | Build React assets into ` dist/ ` | ` make build-frontend ` |
22+ | ` build-docker ` | Build Docker image | ` make build-docker ` |
23+ | ` run ` | Run compiled binary locally | ` make run ` |
24+ | ` run-docker ` | Run smolgit in a container | ` make run-docker ` |
25+ | ` config ` | Generate default config to stdout | ` make config ` |
26+ | ` config-docker ` | Generate config for Docker | ` make config-docker ` |
27+ | ` clean ` | Remove build artifacts | ` make clean ` |
28+ | ` lint ` | Run golangci-lint on Go code | ` make lint ` |
29+ | ` test ` | Run Go unit tests | ` make test ` |
30+ | ` integration-test ` | Run Bats integration tests | ` make integration-test ` |
31+ | ` help ` | Show available make targets | ` make help ` |
3032
3133### Docker usage
34+
3235``` sh
3336# Build image
3437make build-docker
@@ -52,35 +55,41 @@ A minimal example:
5255
5356``` yaml
5457log :
58+ # Color log output
5559 color : true
60+ # Log as json
5661 json : false
62+ # Log level (INFO, DEBUG, TRACE, WARN)
5763 level : DEBUG
5864server :
59- disabled : false
60- jwt_key : " your-secret-key"
65+ jwt_key : " super-salt"
6166 auth_disabled : false
67+ # Disable web server
68+ disabled : false
69+ # Web server address
6270 addr : " :3080"
71+ # Navbar brand string
6372 brand : " smolgit"
64- auth :
65- enabled : false
66- accounts :
67- - login : user
68- password : pass
6973ssh :
74+ # SSH server address
7075 addr : " :3081"
7176git :
72- path : /tmp/smolgit
77+ # Folder to save git repositories
78+ path : ./tmp
79+ # Base for clone string formating
80+ # (e.g. ssh://git@my-git-server.lan/myuser/project.git)
7381 base : " git@my-git-server.lan"
7482 users :
7583 - name : " bob"
76- permissions : " *"
84+ password : " $2y$05$US7wXbew8P9d2h8qL3aC6OMhVcwO.1W6U.hVFBGNj9o9YQO.cSqd2" # htpasswd -nbB admin MySecret123
85+ role : " admin"
7786 keys :
78- - ssh-rsa AAAAB3 ...
87+ - ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQ ... developer@mail.com
7988` ` `
8089
81- * ` server.jwt_key` is mandatory – without it the server will refuse to start.
82- * `git.path` can point to a local `git` binary; if omitted the binary defaults to `/usr/local/bin/git`.
83- * `git.users` controls SSH access; each user has a list of public keys and a permissions string.
90+ - ` server.jwt_key` is mandatory – without it the server will refuse to start.
91+ - ` git.path` can point to a local `git` binary; if omitted the binary defaults to `/usr/local/bin/git`.
92+ - ` git.users` controls SSH access; each user has a list of public keys and a role string.
8493
8594# # Frontend
8695
@@ -104,11 +113,13 @@ pnpm run lint
104113# # Testing
105114
106115# ## Go unit tests
116+
107117` ` ` sh
108118make test
109119` ` `
110120
111121# ## Bats integration tests
122+
112123` ` ` sh
113124make integration-test
114125` ` `
@@ -118,22 +129,23 @@ The Bats tests start a temporary smolgit instance, exercise the CLI, and verify
118129# ## CI
119130
120131GitHub Actions runs :
121- * `make build`
122- * `make lint`
123- * `make config`
124- * `make integration-test`
132+
133+ - ` make build`
134+ - ` make lint`
135+ - ` make config`
136+ - ` make integration-test`
125137
126138See `.github/workflows/test.yml` for details.
127139
128140# # Naming & Coding Conventions
129141
130- | Area | Convention |
131- |------| ------------|
132- | Go packages | lowercase, no underscores |
142+ | Area | Convention |
143+ | -------------- | ------------------------------------------------------ |
144+ | Go packages | lowercase, no underscores |
133145| Go identifiers | camelCase for variables, PascalCase for exported types |
134- | Go structs | Tags use `koanf` style |
135- | Frontend | PascalCase components, camelCase props |
136- | Paths | Use relative paths in imports (e.g. `smolgit/pkg/git`) |
146+ | Go structs | Tags use `koanf` style |
147+ | Frontend | PascalCase components, camelCase props |
148+ | Paths | Use relative paths in imports (e.g. `smolgit/pkg/git`) |
137149
138150# # Gotchas
139151
@@ -154,7 +166,9 @@ make test
154166before pushing. Use the PR title format `[smolgit] <Title>`.
155167
156168# # Commit Messages
169+
157170Follow Conventional Commits :
171+
158172- `feat` : A new feature
159173- `fix` : A bug fix
160174- `docs` : Documentation only changes
0 commit comments