git-publish.1 (6041B)
1 .\" Copyright (C) 2024, 2025 |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 December 3, 2025 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 df 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 .It Fl d 50 Unpublish 51 .Ar repositories : 52 their link in the publicly exposed directory is removed, as are their 53 HTML pages and the post-receive hook that updates them. 54 The HTML index of publicly exposed repositories is updated to no longer 55 reference repositories to be unpublished. 56 If no more repositories are made public, this HTML index is deleted, 57 .It Fl f 58 Force HTML generation from scratch. 59 Enabling this option ensures that HTML pages take into account any 60 changes in the repositories, such as their metadata 61 .Pq see Sx FILES No section . 62 .It Fl g Ar dir_git 63 Directory in which git repositories are publicly exposed. 64 By default, the 65 .Ev GIT_PUBLISH_DIR_GIT 66 environment variable is used. 67 .It Fl u Ar base_url 68 Base URL to make links in the Atom feeds absolute. 69 By default, the 70 .Ev GIT_PUBLISH_BASE_URL 71 environment variable is used. 72 .It Fl w Ar dir_www 73 Directory in which HTML pages are generated. 74 By default, the 75 .Ev GIT_PUBLISH_DIR_WWW 76 environment variable is used. 77 .Pp 78 Pages from each repository are stored in a subdirectory whose name is 79 the repository name, without the 80 .Qq .git 81 suffix that characterizes a bare git repository. 82 The HTML index listing all published repositories, i.e. all repositories 83 stored in the 84 .Ar dir_git 85 directory, is stored at the root of 86 .Ar dir_www . 87 .Pp 88 External HTML resources, such as the CSS file and icons, are assumed to 89 be present in this directory 90 .Po see 91 .Sx FILES 92 section 93 .Pc . 94 .El 95 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 96 .Sh ENVIRONMENT 97 .Bl -tag -width Ds 98 .It Ev GIT_PUBLISH_DIR_GIT 99 Directory in which bare repositories are made public. 100 The default is 101 .Pa /srv/git . 102 .It Ev GIT_PUBLISH_BASE_URL 103 Base URL to make links in the ATOM feed absolute. 104 It has no default value and must be explicitly defined if the 105 .Fl u 106 option is not used, unless publications are to be deleted 107 .Pq option Fl d . 108 .It Ev GIT_PUBLISH_DIR_WWW 109 Directory where public repository HTML pages are stored. 110 The default is 111 .Pa /srv/www/git . 112 .El 113 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 114 .Sh FILES 115 In each bare repository, the content of follow files specifies its 116 metadata: 117 .Bl -tag -width Ds 118 .It Pa description 119 Brief description of the repository. 120 .It Pa owner 121 Owner of repository. 122 .It Pa publication_ban 123 If the file exists, the repository is not authorized to be published. 124 Its purpose is therefore to prevent the accidental publication of a 125 repository that should remain private. 126 .It Pa url 127 Public URL from which the repository can be cloned. 128 .El 129 .Pp 130 To control the appearance of HTML pages, the following files can be 131 defined in the 132 .Ar dir_www 133 directory. 134 Otherwise, the default files provided by git-publish will be used: 135 .Bl -tag -width Ds 136 .It Pa style.css 137 HTML stylesheet. 138 .It Pa favicon.png 139 favicon image (used by graphical browser). 140 .It Pa logo.png 141 32x32 logo. 142 .El 143 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 144 .Sh EXIT 145 .Ex -std 146 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 147 .Sh EXAMPLES 148 Make a bare repository public, i.e. link to it in the 149 .Pa /srv/git 150 directory 151 .Pq default value of Ev GIT_PUBLISH_DIR_GIT . 152 Store generated HTML pages in the 153 .Pa /srv/www/git/ 154 directory 155 .Pq default value of Ev GIT_PUBLISH_DIR_WWW . 156 Make Atom feed URLs to repository commits absolute at URL 157 https://www.example.com/git: 158 .Bd -literal -offset Ds 159 git-publish -u https://www.example.com/git /path/to/repository.git 160 .Ed 161 .Pp 162 Undo the previous publication, i.e. delete the data that made the 163 repository public: 164 .Bd -literal -offset Ds 165 git-publish -d /path/to/repository.git 166 .Ed 167 .Pp 168 Make public a set of bare git repositories: 169 .Bd -literal -offset Ds 170 git-publish -u https://www.example.com/git /path/to/*.git 171 .Ed 172 .Pp 173 Same as above, but using specific directories for public git 174 repositories and WEB pages. 175 In addition, use the environment variable instead of the command-line 176 option to define the base URL where repository HTML pages are stored: 177 .Bd -literal -offset Ds 178 export GIT_PUBLISH_BASE_URL="https://www.example.com/git" 179 git-publish -g /var/git -w /var/www/git /path/to/*.git 180 .Ed 181 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 182 .Sh SEE ALSO 183 .Xr git 1 , 184 .Xr git-daemon 1 , 185 .Xr stagit 1 , 186 .Xr stagit-index 1 , 187 .Xr githooks 5