vole
Clone
Read only, no credentials:
https://rodent.software/vole.git
Write over SSH with a registered key:
git clone ssh://git@rodent.software:2222/vole.git
A free and open-source forge that lives in your Git repo.
|
520470e1
Keenan Nemetz
16d ago
|
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 | ||
|
b7396a11
Keenan Nemetz
6h ago
|
17 | git clone http://host/demo.git # LFS files come through the same URL |
|
520470e1
Keenan Nemetz
16d ago
|
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 | |
|
3abbe749
Keenan Nemetz
16d ago
|
42 | vole admin gc --dry-run # show what is unused |
| 43 | vole admin gc # remove it | |
|
520470e1
Keenan Nemetz
16d ago
|
44 | ``` |
| 45 | ||
|
3abbe749
Keenan Nemetz
16d ago
|
46 | `vole admin gc` keeps files that are still reachable from a repository, an archived CI |
|
520470e1
Keenan Nemetz
16d ago
|
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 | |
|
b7396a11
Keenan Nemetz
6h ago
|
70 | `/<repo>/locks` page shows current locks. |
|
520470e1
Keenan Nemetz
16d ago
|
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. |