README.md (4105B)
1 git repo manager 2 ================ 3 4 `grm` is a minimal, POSIX-compliant shell script for managing git repositories 5 on self-hosted git servers. It is mainly designed to work with [git daemon][1] 6 and [stagit][2], though you don't necessarily need them to run the script. 7 8 Installation 9 ------------ 10 11 Before installing `grm`, make sure you have set up your git server following 12 the instructions in [section 4.4][3] of Pro Git. Optionally, you should also 13 have [git daemon][1] ready for the public access of the repositories, which is 14 documented in [section 4.5][4] of Pro Git. Your git repositories root should 15 have the following structure: 16 17 ``` 18 $GRM_REPOS_ROOT 19 ├── private-repo.git 20 │ ├── branches 21 │ ├── HEAD 22 │ └── ... 23 ├── public-repo.git 24 │ ├── branches 25 │ ├── HEAD 26 │ ├── ... 27 │ └── git-daemon-export-ok 28 └── unlisted-repo.git 29 ├── branches 30 ├── HEAD 31 ├── ... 32 ├── git-daemon-export-ok 33 └── stagit-no-index 34 ``` 35 36 If you want to have a web interface for your repositories, you should also have 37 [stagit][2] compiled and installed on your server. 38 39 To use git repo manager, edit the `grm` script to fill in some configurations, 40 41 ```sh 42 # root directory of git repositories 43 GRM_REPOS_ROOT="/home/git" 44 45 # default owner 46 GRM_OWNER="yourname" 47 48 # default url prefix (without ending slash) 49 GRM_URL_PREFIX="git://git.domain.tld" 50 51 # path of the post-receive hooks for stagit 52 GRM_POSTRECV_HOOK="/home/git/.post-receive" 53 54 # root directory of stagit web pages 55 STAGIT_WEB_ROOT="/srv/git" 56 ``` 57 58 then 59 60 ``` 61 $ make install 62 ``` 63 64 An example of the `post-receive` hook for stagit can be found [here][5]. Note 65 that the hook itself needs some further configuration. 66 67 Usage 68 ----- 69 70 ``` 71 $ grm help 72 usage: grm <command> [<args>] 73 74 Git repo manager, manage git repositories on self-hosted git servers. 75 76 commands: 77 new create a new repo 78 info repo_name display metadata of the repo 79 ls list all repos 80 ls public list public repos 81 ls private list private repos 82 ls unlisted list unlisted repos 83 rm repo1 [repo2..] remove repos 84 rc recompile stagit index 85 rc repo1 [repo2..] recompile stagit pages for repos, 86 and recompile index 87 rca recompile all public repos 88 help show help 89 ``` 90 91 If you have created a `git` user for managing git repositories, make sure the 92 `git` user has write access to all the directories in the config, and run the 93 script on the server as: 94 95 ```sh 96 $ doas -u git -- grm <command> [<args>] 97 ``` 98 99 or 100 101 ```sh 102 $ sudo -u git -- grm <command> [<args>] 103 ``` 104 105 You could also run the script on your local machine using ssh, 106 107 ```sh 108 $ ssh git@domain.tld -- grm <command> [<args>] 109 ``` 110 111 or simply create an alias if you find it cumbersome: 112 113 ```sh 114 alias grm="ssh git@domain.tld -- grm" 115 ``` 116 117 Examples 118 -------- 119 120 ```console 121 $ grm new 122 repo name 123 > grmr 124 visibility: 125 1) public 126 2) private 127 3) unlisted (hide from index) 128 enter index [default: 1] 129 > 1 130 description [a work in progress] 131 > grm redux 132 owner [yourname] 133 > kst 134 clone url [git://domain.tld/grmr] 135 > git://git.domain.tld/grmr 136 Initialized empty Git repository in /home/git/grmr.git/ 137 writing stagit metadata... 138 setting visibility... 139 installing stagit post-receive hook... 140 done! 141 $ grm ls 142 grm 143 grmr 144 $ grm info grmr 145 name: grmr 146 visibility: public 147 description: grm redux 148 owner: kst 149 url: git://git.domain.tld/grmr 150 $ grm rc grmr 151 [grmr] recompiling stagit pages... 152 [index] rebuilding index... 153 [grmr] done! 154 [index] done! 155 recompilation done! 156 $ grm rm grmr 157 remove grmr? [y/N] y 158 [index] rebuilding index... 159 [index] done! 160 $ grm ls 161 grm 162 ``` 163 164 License 165 ------- 166 167 `grm` is licensed under the MIT license. 168 169 [1]: https://git-scm.com/docs/git-daemon 170 [2]: https://codemadness.org/git/stagit/ 171 [3]: https://git-scm.com/book/en/v2/Git-on-the-Server-Setting-Up-the-Server 172 [4]: https://git-scm.com/book/en/v2/Git-on-the-Server-Git-Daemon 173 [5]: https://sink.krj.st/stagit/file/post-receive.html