git-wad.1 (8025B)
1 .\" Copyright (C) 2023-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 November 15, 2024 16 .Dt GIT-WAD 1 17 .Os 18 .Sh NAME 19 .Nm git-wad 20 .Nd manage files with git, but not their content 21 .Sh SYNOPSIS 22 .Nm 23 .Cm checkout 24 .Nm 25 .Cm fetch Op Fl 1a 26 .Nm 27 .Cm fsck Op Fl r 28 .Nm 29 .Cm init 30 .Nm 31 .Cm prune Op Fl 1a 32 .Nm 33 .Cm pull Op Fl 1a 34 .Nm 35 .Cm push Op Fl 1a 36 .Nm 37 .Cm status Op Fl 1a 38 .Sh DESCRIPTION 39 .Nm 40 allows files to be managed via git(1) without git managing their 41 content. 42 git then only archives the fingerprints of these files, here called WAD 43 files. 44 These fingerprints are used both to differentiate between different 45 versions of a WAD file and as pointers to its data. 46 The latter can be archived elsewhere than on the git repository that 47 manages their fingerprint, and are accessible via a potentially distinct 48 protocol. 49 .Pp 50 Even without tracking their content, being able to follow and 51 historicize files in git makes it possible to manage the consistency of 52 a source tree with the third-party files needed for the project, all at 53 once. 54 Third-party files whose full management by git would raise problems of 55 memory occupation, disk space or checking times. 56 .Pp 57 .Nm 58 provides a set of sub-commands for managing WAD files. 59 The list of files to be managed is controlled by the 60 .Xr gitattributes 5 61 file 62 .Po see 63 .Sx FILES 64 section 65 .Pc . 66 The subcommands are as follows: 67 .Bl -tag -width Ds 68 .It Cm checkout 69 Restores WAD file data as intended by the HEAD. 70 It updates the contents of WAD files whose data has 71 .Em already 72 been transferred locally 73 .Pq see Cm fetch . 74 .It Cm fetch 75 Transfers WAD file contents locally. 76 The URL of the WAD repository from which data will be transferred is 77 defined by the 78 .Ev GIT_WAD_REMOTE_FETCH 79 environment variable. 80 The default setting is to transfer WAD file data for the entire HEAD 81 history. 82 .Pp 83 The options are as follows: 84 .Bl -tag -width Ds 85 .It Fl 1 86 Transfers only WAD file data for the HEAD, not its history, i.e. it 87 transfers neither their previous version nor the contents of WAD files 88 that are no longer referenced. 89 .It Fl a 90 Transfers all versions of WAD files referenced in the complete 91 repository history, i.e. in all commits of all branches. 92 .El 93 .It Cm fsck 94 Checks locally stored WAD files. 95 If the 96 .Fl r 97 option is set, corrupted files are deleted. 98 .It Cm init 99 Configures the git repository for WAD file management. 100 Must be called in the working tree before any other 101 .Nm 102 command. 103 .It Cm prune 104 Removes non-referenced WAD file data from local storage. 105 By default, local data is retained for WAD files in the HEAD history. 106 .Pp 107 The options are as follows: 108 .Bl -tag -width Ds 109 .It Fl 1 110 Removes all WAD file data stored locally, with the exception of WAD file 111 data of the HEAD. 112 .It Fl a 113 Keep local data for all versions of WAD files referenced in the complete 114 repository history, i.e. in all commits of all branches. 115 Only untracked WAD data is removed. 116 This is a very special case in which deleted files would have the same 117 naming convention as WAD data and would be stored in the WAD objects 118 directory without being tracked by 119 .Xr git 1 . 120 .El 121 .It Cm pull 122 Transfers locally and restores WAD file data as intended by HEAD. 123 This is a shortcut to the combination of the 124 .Cm fetch 125 and 126 .Cm checkout 127 subcommands. 128 See 129 .Cm fetch 130 for the URL of the WAD repository from which WAD data is transferred and 131 a list of available options. 132 .It Cm push 133 Transfers data from WAD files to the remote WAD repository. 134 The remote URL is defined by the 135 .Ev GIT_WAD_REMOTE_PUSH 136 environment variable. 137 The default setting is to transfer WAD file data for the entire HEAD 138 history. 139 .Pp 140 The options are as follows: 141 .Bl -tag -width Ds 142 .It Fl 1 143 Transfers only WAD file data for the HEAD, not its history, i.e. it 144 transfers neither their previous version nor the contents of WAD files 145 that are no longer referenced. 146 .It Fl a 147 Transfers all versions of WAD files referenced in the complete 148 repository history, i.e. in all commits of all branches store locally. 149 .El 150 .It Cm status 151 Displays resolved, unrestored and orphaned WAD files for the current 152 HEAD commit. 153 The first are WAD files ready for use; the second are WAD 154 files whose data is transferred locally but whose contents have yet to 155 be restored 156 .Pq see Cm checkout ; 157 the third are WAD files whose data must be transferred locally before 158 their contents can be restored 159 .Pq see Cm pull . 160 .Pp 161 The initialisation status is also displayed 162 .Pq see Cm init , 163 as well as the number of WAD file data that can be removed locally 164 .Pq see Cm prune . 165 .Pp 166 The options are those of the 167 .Cm prune 168 subcommand and affect the reported number of WAD file data to remove. 169 .El 170 .Sh ENVIRONMENT 171 .Bl -tag -width Ds 172 .It Ev GIT_WAD_OBJDIR 173 Path where WAD files are stored. 174 The default is the 175 .Pa .git/wad 176 subdirectory of the current working tree. 177 .It Ev GIT_WAD_REMOTE_FETCH 178 URL of the remote repository 179 .Em from 180 which WAD file data is transfered. 181 By default, this is the fetch URL of the 182 .Li origin 183 git repository. 184 .It Ev GIT_WAD_REMOTE_PUSH 185 URL of the remote repository 186 .Em to 187 which WAD file data is transfered. 188 By default, this is the push URL of the 189 .Li origin 190 git repository. 191 .It Ev GIT_WAD_VERBOSE 192 Causes 193 .Nm 194 to print debugging messages. 195 The default value is 196 .Li 0 , 197 i.e. no debug messages are printed. 198 .El 199 .Sh FILES 200 .Bl -tag -width Ds 201 .It Pa .git_wad.cfg 202 File at the root of the working tree in which environment variables 203 controlling 204 .Nm 205 can be overwritten 206 .Po see 207 .Sx ENVIRONMENT 208 section 209 .Pc . 210 This is a shell script whose syntax must respect the POSIX shell. 211 Here's an example of how to define an SSH remote: 212 .Bd -literal -offset Ds 213 GIT_WAD_REMOTE_FETCH="user@remote:repo_wad" 214 GIT_WAD_REMOTE_PUSH="user@remote:repo_wad" 215 .Ed 216 .It Pa .gitattributes 217 Regular 218 .Xr gitattributes 5 219 file in which you define which files are to be managed by 220 .Nm . 221 To do this, simply add the 222 .Li filter=wad 223 attribute to these files. 224 For example, to manage the 225 .Pa test.png 226 image and all 227 pdf files with 228 .Nm , 229 the following lines must be added to your 230 .Pa .gitattributes : 231 .Bd -literal -offset Ds 232 test.png filter=wad 233 *.pdf filter=wad 234 .Ed 235 .El 236 .Sh EXIT STATUS 237 .Ex -std 238 .Sh EXAMPLES 239 Use 240 .Nm 241 to archive pdf files of a git repository: 242 .Bd -literal -offset Ds 243 cd /path/to/git/repository 244 git wad init 245 echo "*.pdf filter=wad" >> .gitattributes 246 git add document.pdf 247 git commit -m "Add a PDF document managed by git-wad" 248 git push origin 249 git wad push 250 .Ed 251 .Pp 252 Clone a git repository containing WAD files: 253 .Bd -literal -offset Ds 254 git clone user@remote:repo.git 255 cd repo 256 git wad init 257 git wad pull 258 .Ed 259 .Pp 260 Same as above, but saves disk space by transferring only the contents of 261 WAD files referenced by HEAD: 262 .Bd -literal -offset Ds 263 git clone user@remote:repo.git 264 cd repo 265 git wad init 266 git wad pull -1 267 .Ed 268 .Pp 269 Synchronise the local working tree with the state of the 270 .Ar origin 271 repository and update the contents of WAD files accordingly: 272 .Bd -literal -offset Ds 273 git pull origin 274 git wad pull 275 .Ed 276 .Pp 277 Check locally stored WAD files and delete corrupted ones before 278 retransferring missing files: 279 .Bd -literal -offset Ds 280 git wad fsck -r 281 git wad pull 282 .Ed 283 .Pp 284 Make space on disk by deleting the contents of WAD files that are not 285 referenced by HEAD: 286 .Bd -literal -offset Ds 287 git wad prune -1 288 .Ed 289 .Pp 290 Transfer all locally stored WAD files to another remote repository: 291 .Bd -literal -offset Ds 292 GIT_WAD_REMOTE_PUSH="user@another_remote:repo_wad" \e 293 git wad push -a 294 .Ed 295 .Sh SEE ALSO 296 .Xr git 1 , 297 .Xr gitattributes 5