# GitPad A lightweight git web interface with: * **editing support** (create, edit, move and remove files) * **Markdown rendering** (for files named `*.md`) * a **multi-user mode** with file sharing & collaborative editing You can install GitPad with: ``` $ cargo install gitpad ``` GitPad needs to be started from inside of a bare Git repository. For example: ``` $ git init --bare example.git $ cd example.git/ $ gitpad Listening on http://127.0.0.1:8000 ``` By default GitPad is in single-user mode, serving the branch pointed to by `HEAD`. **WARNING**: The `lua` feature is enabled by default. Lua sandboxing is still experimental, so giving users access who you don't trust might lead to a system compromise. ## Multi-user mode Multi-user mode requires you to set up a reverse-proxy that authenticates users and sets the `Username` header. Every user gets their own private Git branch, named exactly like their username and served under `/~{username}`. Users can share files/directories with other users by creating a `.shares.txt` file. The simplest authentication mechanism is HTTP Basic Auth. With NGINX a reverse-proxy could be configured as follows: ```nginx server { listen 80; listen [::]:80; server_name notes.localhost; client_max_body_size 5M; location / { auth_basic 'Restricted'; auth_basic_user_file /etc/nginx/gitpad_passwd; proxy_set_header Username $remote_user; proxy_pass http://localhost:8000; # Or if you start GitPad with --socket /srv/sockets/gitpad.sock # proxy_pass http://unix:/srv/sockets/gitpad.sock; } } ``` For instructions on how to create the `auth_basic_user_file`, refer to the [NGINX documentation](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-http-basic-authentication/). Once you have set this up start GitPad in multi-user mode by running it with the `-m` flag. ## Configuring committer identities In single-user mode GitPad just uses the committer identity from your git config. In multi-user mode GitPad defaults to `{username} <{username}@localhost.invalid>`. Committer identities can be configured by creating a `users.toml` file in the `gitpad` branch, with sections like the following: ```toml [johndoe] name = "John Doe" email = "john@example.com" ``` ## Lua templates You can define Lua functions in `.lua` files within the `modules/` directory and then call them within `.md` files using the `{{modulename.functionname}}` syntax. For example if you create `modules/example.lua` with: ```lua function greet(args) return 'Hello ' .. args[1] .. '!' end function sum(args) return args.x + args.y end return {greet=greet, sum=sum} ``` within Markdown files `{{example.greet|world}}` will become `Hello world!` and `{{example.sum|x=3|y=5}}` will become 8. Note that: * If no module name is given it defaults to `default` so e.g. `{{foo}}` will attempt to call the `foo` function defined in `modules/default.lua`. * In order to pass `|` or `}}` within arguments you need to escape them by prefixing a slash e.g. `{{foo| \| \}} }}`. * Within `
` and `` tags and HTML comments no special syntax is interpreted.
* Note that none of these constructs can be nested. E.g. `{{foo|{{bar}} }}` or
  `{{foo|test}}` will not work as you might expect.

## Contributing

Feedback, bug reports and suggestions are welcome!