git-publish.1 (7288B)
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 May 27, 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 u Ar base_url 28 .Op Fl w Ar dir_www 29 .Ar repository No ... 30 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 31 .Sh DESCRIPTION 32 .Nm 33 helps make bare git repositories public. 34 It creates a link to them in a directory that would be publicly exposed 35 via a git server 36 .Pq e.g. Xr git-daemon 1 . 37 .Pp 38 It also generates HTML pages of their contents 39 .Pq commits, files, license, README, etc. 40 and an index listing published repositories. 41 These files are stored in a directory which can then be publicly exposed 42 via a simple static WEB server. 43 To make sure they're up to date, a post-receipt hook is added to 44 published repositories to update HTML pages on new commits 45 .Pq see Xr githooks 5 46 .Pp 47 The options are as follows: 48 .Bl -tag -width Ds 49 .\"""""""""""""""""""""""""""""""""" 50 .It Fl d 51 Unpublish 52 .Ar repositories : 53 their link in the publicly exposed directory is removed, as are their 54 HTML pages and the post-receive hook that updates them. 55 The HTML index of publicly exposed repositories is updated to no longer 56 reference repositories to be unpublished. 57 If no more repositories are made public, this HTML index is deleted, 58 .\"""""""""""""""""""""""""""""""""" 59 .It Fl f 60 Force HTML generation from scratch. 61 Enabling this option ensures that HTML pages take into account any 62 changes in the repositories, such as their metadata 63 .Pq see Sx FILES No section . 64 .\"""""""""""""""""""""""""""""""""" 65 .It Fl g Ar dir_git 66 Directory in which git repositories are publicly exposed. 67 By default, the 68 .Ev GIT_PUBLISH_DIR_GIT 69 environment variable is used. 70 .\"""""""""""""""""""""""""""""""""" 71 .It Fl m 72 Move the repositories to publish to the 73 .Ar dir_git 74 directory, 75 which is the directory where git repositories are publicly accessible. 76 The paths to the original repositories become symbolic links to their 77 published repositories. 78 This is actually the opposite of the default behavior, in which 79 published repositories are symbolic links to the original git 80 repositories. 81 .Pp 82 Ensuring that the published repository is a directory rather than a 83 symbolic link may be a server constraint. 84 For example, for security reasons, the server might serve public 85 repositories via a chroot jail, thereby prohibiting the use of links 86 that would take users outside it. 87 .\"""""""""""""""""""""""""""""""""" 88 .It Fl u Ar base_url 89 Base URL to make links in the Atom feeds absolute. 90 By default, the 91 .Ev GIT_PUBLISH_BASE_URL 92 environment variable is used. 93 .\"""""""""""""""""""""""""""""""""" 94 .It Fl w Ar dir_www 95 Directory in which HTML pages are generated. 96 By default, the 97 .Ev GIT_PUBLISH_DIR_WWW 98 environment variable is used. 99 .Pp 100 Pages from each repository are stored in a subdirectory whose name is 101 the repository name, without the 102 .Qq .git 103 suffix that characterizes a bare git repository. 104 The HTML index listing all published repositories, i.e. all repositories 105 stored in the 106 .Ar dir_git 107 directory, is stored at the root of 108 .Ar dir_www . 109 .Pp 110 External HTML resources, such as the CSS file and icons, are assumed to 111 be present in this directory 112 .Po see 113 .Sx FILES 114 section 115 .Pc . 116 .El 117 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 118 .Sh ENVIRONMENT 119 .Bl -tag -width Ds 120 .\"""""""""""""""""""""""""""""""""" 121 .It Ev GIT_PUBLISH_BASE_URL 122 Base URL to make links in the ATOM feed absolute. 123 It has no default value and must be explicitly defined if the 124 .Fl u 125 option is not used, unless publications are to be deleted 126 .Pq option Fl d . 127 .\"""""""""""""""""""""""""""""""""" 128 .It Ev GIT_PUBLISH_DIR_GIT 129 Directory in which bare repositories are made public. 130 The default is 131 .Pa /srv/git . 132 .\"""""""""""""""""""""""""""""""""" 133 .It Ev GIT_PUBLISH_DIR_WWW 134 Directory where public repository HTML pages are stored. 135 The default is 136 .Pa /srv/www/git . 137 .El 138 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 139 .Sh FILES 140 In each bare repository, the content of follow files specifies its 141 metadata: 142 .Bl -tag -width Ds 143 .\"""""""""""""""""""""""""""""""""" 144 .It Pa description 145 Brief description of the repository. 146 .\"""""""""""""""""""""""""""""""""" 147 .It Pa owner 148 Owner of repository. 149 .\"""""""""""""""""""""""""""""""""" 150 .It Pa publication_ban 151 If the file exists, the repository is not authorized to be published. 152 Its purpose is therefore to prevent the accidental publication of a 153 repository that should remain private. 154 .\"""""""""""""""""""""""""""""""""" 155 .It Pa url 156 Public URL from which the repository can be cloned. 157 .El 158 .Pp 159 To control the appearance of HTML pages, the following files can be 160 defined in the 161 .Ar dir_www 162 directory. 163 Otherwise, the default files provided by git-publish will be used: 164 .Bl -tag -width Ds 165 .\"""""""""""""""""""""""""""""""""" 166 .It Pa style.css 167 HTML stylesheet. 168 .\"""""""""""""""""""""""""""""""""" 169 .It Pa favicon.png 170 favicon image (used by graphical browser). 171 .\"""""""""""""""""""""""""""""""""" 172 .It Pa logo.png 173 32x32 logo. 174 .El 175 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 176 .Sh EXIT 177 .Ex -std 178 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 179 .Sh EXAMPLES 180 Make a bare repository public, i.e. link to it in the 181 .Pa /srv/git 182 directory 183 .Pq default value of Ev GIT_PUBLISH_DIR_GIT . 184 Store generated HTML pages in the 185 .Pa /srv/www/git/ 186 directory 187 .Pq default value of Ev GIT_PUBLISH_DIR_WWW . 188 Make Atom feed URLs to repository commits absolute at URL 189 https://www.example.com/git: 190 .Bd -literal -offset Ds 191 git-publish -u https://www.example.com/git /path/to/repository.git 192 .Ed 193 .Pp 194 Undo the previous publication, i.e. delete the data that made the 195 repository public: 196 .Bd -literal -offset Ds 197 git-publish -d /path/to/repository.git 198 .Ed 199 .Pp 200 Make public a set of bare git repositories: 201 .Bd -literal -offset Ds 202 git-publish -u https://www.example.com/git /path/to/*.git 203 .Ed 204 .Pp 205 Same as above, but using specific directories for public git 206 repositories and WEB pages. 207 In addition, use the environment variable instead of the command-line 208 option to define the base URL where repository HTML pages are stored: 209 .Bd -literal -offset Ds 210 export GIT_PUBLISH_BASE_URL="https://www.example.com/git" 211 git-publish -g /var/git -w /var/www/git /path/to/*.git 212 .Ed 213 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 214 .Sh SEE ALSO 215 .Xr git 1 , 216 .Xr git-daemon 1 , 217 .Xr stagit 1 , 218 .Xr stagit-index 1 , 219 .Xr githooks 5