vole

Clone

Read only, no credentials:

https://rodent.software/git/vole.git

Write over SSH with a registered key:

git clone ssh://git@0.0.0.0:2222/vole.git

A free and open-source forge that lives in your Git repo.

Docs: rewrite the README and organize the guides

520470e19cd906bd6fff987e2d132d793ce56486 · Keenan Nemetz · 16d ago · parent c5902451

Docs: rewrite the README and organize the guides

Replace the long README with a landing page, split feature details into focused guides, and remove the roadmap and spike notes. Update comments that referenced them.

docs/lfs.md +74

@@ -0,0 +1,74 @@
	1	# LFS and file locking
	2
	3	Large files should not force you onto a hosted service. With Git LFS, Git keeps a
	4	small pointer file and Vole stores the actual file on infrastructure you control.
	5	Repositories share one storage pool, so the same file is kept only once even if
	6	several repositories use it.
	7
	8	## Using LFS
	9
	10	```sh
	11	git lfs install # once per machine
	12	git lfs track "*.psd"
	13	git add .gitattributes art/hero.psd
	14	git commit -m "add the hero art"
	15	git push origin main
	16
	17	git clone http://host/git/demo.git # LFS files come through the same URL
	18	```
	19
	20	Writes use the SSH key you already push with. Reads use the normal HTTP clone URL.
	21	There is no token to create and no second server to configure.
	22
	23	A repository can only download the files it actually uses. Knowing the file's hash
	24	is not enough, because each repository has its own view of the shared storage.
	25
	26	## Limits and warnings
	27
	28	```toml
	29	lfs_object_max_bytes = 2147483648 # one file; larger files are refused
	30	lfs_warn_bytes = 5242880 # warn about raw binaries this big
	31	```
	32
	33	- If you commit a binary larger than `lfs_warn_bytes` without LFS, Vole accepts
	34	the push but warns you and shows the `git lfs track` command.
	35	- If you push a pointer whose file was never uploaded, Vole refuses the push,
	36	because nobody would be able to check out that commit.
	37	- Set `lfs_warn_bytes = 0` to turn the warning off.
	38
	39	## Cleaning up
	40
	41	```sh
	42	vole gc --dry-run # show what is unused
	43	vole gc # remove it
	44	```
	45
	46	`vole gc` keeps files that are still reachable from a repository, an archived CI
	47	log, or a published build artifact. It also repairs each repository's links into
	48	the shared store. Files newer than `--grace` (one hour by default) are kept,
	49	because an upload that has not been pushed yet is not garbage.
	50
	51	See [Operations](operations.md#clean-up-stored-files) for recovery and scheduling
	52	notes.
	53
	54	## Locking files
	55
	56	Some files cannot be merged by Git: art, audio, models, levels. You can reserve
	57	one before editing it. Locking uses the same SSH connection as everything else.
	58
	59	```sh
	60	git lfs lock art/hero.psd # nobody else's push can change this path
	61	git lfs unlock art/hero.psd # release it
	62	git lfs locks # show who holds what
	63	```
	64
	65	While a file is locked, Vole refuses any push that changes it. The server enforces
	66	this, so it works even for a plain `git push` without a client-side hook.
	67
	68	An admin can push past a lock. That override is recorded in `data/audit.log`;
	69	otherwise a lock held by someone who has left would block the file forever. The
	70	`/r/<repo>/locks` page shows current locks.
	71
	72	Locks are not part of a clone. They live beside the account list in
	73	`data/users.db`, because they are temporary state and should not come back from
	74	history.