git-publish.1 (8296B)
1 .\" Copyright (C) 2024-2026 |Méso|Star> (contact@meso-star.com) 2 .\" 3 .\" This program is free software: you can redistribute it and/or modify 4 .\" it under the terms of the GNU General Public License as published by 5 .\" the Free Software Foundation, either version 3 of the License, or 6 .\" (at your option) any later version. 7 .\" 8 .\" This program is distributed in the hope that it will be useful, 9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of 10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11 .\" GNU General Public License for more details. 12 .\" 13 .\" You should have received a copy of the GNU General Public License 14 .\" along with this program. If not, see <http://www.gnu.org/licenses/>. 15 .Dd June 20, 2026 16 .Dt GIT-PUBLISH 1 17 .Os 18 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 19 .Sh NAME 20 .Nm git-publish 21 .Nd make public bare repositories 22 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 23 .Sh SYNOPSIS 24 .Nm 25 .Op Fl dfm 26 .Op Fl g Ar dir_git 27 .Op Fl s Ar group 28 .Op Fl u Ar base_url 29 .Op Fl w Ar dir_www 30 .Ar repository No ... 31 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 32 .Sh DESCRIPTION 33 .Nm 34 helps make bare git repositories public. 35 It creates a link to them in a directory that would be publicly exposed 36 via a git server 37 .Pq e.g. Xr git-daemon 1 . 38 .Pp 39 It also generates HTML pages of their contents 40 .Pq commits, files, license, README, etc. 41 and an index listing published repositories. 42 These files are stored in a directory which can then be publicly exposed 43 via a simple static WEB server. 44 To make sure they're up to date, a post-receipt hook is added to 45 published repositories to update HTML pages on new commits 46 .Pq see Xr githooks 5 47 .Pp 48 The options are as follows: 49 .Bl -tag -width Ds 50 .\"""""""""""""""""""""""""""""""""" 51 .It Fl d 52 Unpublish 53 .Ar repositories : 54 their link in the publicly exposed directory is removed, as are their 55 HTML pages and the post-receive hook that updates them. 56 The HTML index of publicly exposed repositories is updated to no longer 57 reference repositories to be unpublished. 58 If no more repositories are made public, this HTML index is deleted, 59 .\"""""""""""""""""""""""""""""""""" 60 .It Fl f 61 Force HTML generation from scratch. 62 Enabling this option ensures that HTML pages take into account any 63 changes in the repositories, such as their metadata 64 .Pq see Sx FILES No section . 65 .\"""""""""""""""""""""""""""""""""" 66 .It Fl g Ar dir_git 67 Directory in which git repositories are publicly exposed. 68 By default, the 69 .Ev GIT_PUBLISH_DIR_GIT 70 environment variable is used. 71 .\"""""""""""""""""""""""""""""""""" 72 .It Fl m 73 Move the repositories to publish to the 74 .Ar dir_git 75 directory, 76 which is the directory where git repositories are publicly accessible. 77 The paths to the original repositories become symbolic links to their 78 published repositories. 79 This is actually the opposite of the default behavior, in which 80 published repositories are symbolic links to the original git 81 repositories. 82 .Pp 83 Ensuring that the published repository is a directory rather than a 84 symbolic link may be a server constraint. 85 For example, for security reasons, the server might serve public 86 repositories via a chroot jail, thereby prohibiting the use of links 87 that would take users outside it. 88 .\"""""""""""""""""""""""""""""""""" 89 .It Fl s Ar group 90 Grant write access to the HTML content to the 91 .Ar group 92 specified as an argument. 93 This way, the web pages in a repository with shared write access can be 94 automatically updated by the post-receive hook, regardless of who 95 committed the changes, provided that the committer is a member of the 96 .Ar group . 97 .Pp 98 Note that the group associated with the HTML content is not necessarily 99 the same as that of the git repository. 100 Therefore, for a committer to be able to update both the content of the 101 git repository and that of its HTML content, they must be a member of 102 both groups. 103 .\"""""""""""""""""""""""""""""""""" 104 .It Fl u Ar base_url 105 Base URL to make links in the Atom feeds absolute. 106 By default, the 107 .Ev GIT_PUBLISH_BASE_URL 108 environment variable is used. 109 .\"""""""""""""""""""""""""""""""""" 110 .It Fl w Ar dir_www 111 Directory in which HTML pages are generated. 112 By default, the 113 .Ev GIT_PUBLISH_DIR_WWW 114 environment variable is used. 115 .Pp 116 Pages from each repository are stored in a subdirectory whose name is 117 the repository name, without the 118 .Qq .git 119 suffix that characterizes a bare git repository. 120 The HTML index listing all published repositories, i.e. all repositories 121 stored in the 122 .Ar dir_git 123 directory, is stored at the root of 124 .Ar dir_www . 125 .Pp 126 External HTML resources, such as the CSS file and icons, are assumed to 127 be present in this directory 128 .Po see 129 .Sx FILES 130 section 131 .Pc . 132 .El 133 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 134 .Sh ENVIRONMENT 135 .Bl -tag -width Ds 136 .\"""""""""""""""""""""""""""""""""" 137 .It Ev GIT_PUBLISH_BASE_URL 138 Base URL to make links in the ATOM feed absolute. 139 It has no default value and must be explicitly defined if the 140 .Fl u 141 option is not used, unless publications are to be deleted 142 .Pq option Fl d . 143 .\"""""""""""""""""""""""""""""""""" 144 .It Ev GIT_PUBLISH_DIR_GIT 145 Directory in which bare repositories are made public. 146 The default is 147 .Pa /srv/git . 148 .\"""""""""""""""""""""""""""""""""" 149 .It Ev GIT_PUBLISH_DIR_WWW 150 Directory where public repository HTML pages are stored. 151 The default is 152 .Pa /srv/www/git . 153 .El 154 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 155 .Sh FILES 156 In each bare repository, the content of follow files specifies its 157 metadata: 158 .Bl -tag -width Ds 159 .\"""""""""""""""""""""""""""""""""" 160 .It Pa description 161 Brief description of the repository. 162 .\"""""""""""""""""""""""""""""""""" 163 .It Pa owner 164 Owner of repository. 165 .\"""""""""""""""""""""""""""""""""" 166 .It Pa publication_ban 167 If the file exists, the repository is not authorized to be published. 168 Its purpose is therefore to prevent the accidental publication of a 169 repository that should remain private. 170 .\"""""""""""""""""""""""""""""""""" 171 .It Pa url 172 Public URL from which the repository can be cloned. 173 .El 174 .Pp 175 To control the appearance of HTML pages, the following files can be 176 defined in the 177 .Ar dir_www 178 directory. 179 Otherwise, the default files provided by git-publish will be used: 180 .Bl -tag -width Ds 181 .\"""""""""""""""""""""""""""""""""" 182 .It Pa style.css 183 HTML stylesheet. 184 .\"""""""""""""""""""""""""""""""""" 185 .It Pa favicon.png 186 favicon image (used by graphical browser). 187 .\"""""""""""""""""""""""""""""""""" 188 .It Pa logo.png 189 32x32 logo. 190 .El 191 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 192 .Sh EXIT 193 .Ex -std 194 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 195 .Sh EXAMPLES 196 Make a bare repository public, i.e. link to it in the 197 .Pa /srv/git 198 directory 199 .Pq default value of Ev GIT_PUBLISH_DIR_GIT . 200 Store generated HTML pages in the 201 .Pa /srv/www/git/ 202 directory 203 .Pq default value of Ev GIT_PUBLISH_DIR_WWW . 204 Make Atom feed URLs to repository commits absolute at URL 205 https://www.example.com/git: 206 .Bd -literal -offset Ds 207 git-publish -u https://www.example.com/git /path/to/repo.git 208 .Ed 209 .Pp 210 Undo the previous publication, i.e. delete the data that made the 211 repository public: 212 .Bd -literal -offset Ds 213 git-publish -d /path/to/repo.git 214 .Ed 215 .Pp 216 Grant write access to HTML content of the repository to members of the 217 .Ql www 218 group, so that this content can be updated automatically when the 219 repository is updated, provided that the committer has write access to 220 the git repository and is a member of the 221 .Ql www 222 group: 223 .Bd -literal -offset Ds 224 git-publish -s www -u https://www.example.com/git /path/to/repo.git 225 .Ed 226 .Pp 227 Make public a set of bare git repositories: 228 .Bd -literal -offset Ds 229 git-publish -u https://www.example.com/git /path/to/*.git 230 .Ed 231 .Pp 232 Same as above, but using specific directories for public git 233 repositories and WEB pages. 234 In addition, use the environment variable instead of the command-line 235 option to define the base URL where repository HTML pages are stored: 236 .Bd -literal -offset Ds 237 export GIT_PUBLISH_BASE_URL="https://www.example.com/git" 238 git-publish -g /var/git -w /var/www/git /path/to/*.git 239 .Ed 240 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 241 .Sh SEE ALSO 242 .Xr git 1 , 243 .Xr git-daemon 1 , 244 .Xr stagit 1 , 245 .Xr stagit-index 1 , 246 .Xr githooks 5