commit 4735f508ce8eda7b2cb517c4bd5c91f2584619e4
parent f99b0ef9257f3344a0d6d1b0a76bfaa2ef6bbb9d
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Sun, 3 Mar 2024 16:58:46 +0100
Finalize a first version of the manual page
Document subcommands and their options, environment variables and files.
An example section should be added for a quick start in using git-wad.
Diffstat:
| M | git-wad.1 | | | 164 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- |
1 file changed, 159 insertions(+), 5 deletions(-)
diff --git a/git-wad.1 b/git-wad.1
@@ -22,17 +22,17 @@
.Nm
.Cm checkout
.Nm
-.Cm fetch Op Fl -all
+.Cm fetch Op Fl 1a
.Nm
.Cm init
.Nm
-.Cm prune Op Fl -all
+.Cm prune Op Fl 1a
.Nm
-.Cm pull Op Fl -all
+.Cm pull Op Fl 1a
.Nm
-.Cm push Op Fl -all
+.Cm push Op Fl 1a
.Nm
-.Cm status Op Fl -all
+.Cm status Op Fl 1a
.Sh DESCRIPTION
.Nm
allows files to be managed via git(1) without git managing their
@@ -51,5 +51,159 @@ a source tree with the third-party files needed for the project, all at
once.
Third-party files whose full management by git would raise problems of
memory occupation, disk space or checking times.
+.Pp
+.Nm
+provides a set of sub-commands for managing WAD files.
+The list of files to be managed is controlled by the
+.Xr gitattributes 5
+file
+.Pq see Sx FILES No section .
+The subcommands are as follows:
+.Bl -tag -width Ds
+.It Cm checkout
+Restores WAD file data as intended by the HEAD.
+It updates the contents of WAD files whose data has
+.Em already
+been transferred locally
+.Pq see Cm fetch .
+.It Cm fetch
+Transfers WAD file contents locally.
+The URI of the WAD repository from which data will be transferred is
+defined by the
+.Ev GIT_WAD_REMOTE_FETCH
+environment variable.
+The default setting is to transfer WAD file data for the entire HEAD
+history.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl 1
+Transfers only WAD file data for the HEAD not its history, i.e. it
+transfers neither their previous version nor the contents of WAD files
+that are no longer referenced.
+.It Fl a
+Transfers all versions of WAD files referenced in the complete
+repository history, i.e. in all commits of all branches.
+.El
+.It Cm init
+Configures the git repository for WAD file management.
+.It Cm prune
+Removes non-referenced WAD file data from local storage.
+By default, local data is retained for WAD files in the current history.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl 1
+Removes all WAD file data stored locally, with the exception of WAD file
+data of the HEAD.
+.It Fl a
+Keep local data for all versions of WAD files referenced in the complete
+repository history, i.e. in all commits of all branches.
+Only untracked WAD data is removed.
+This is a very special case in which deleted files would have the same
+naming convention as WAD data and would be stored in the WAD objects
+directory without being tracked by
+.Xr git 1 .
+.El
+.It Cm pull
+Transfers locally and restores WAD file data as intended by HEAD.
+This is a shortcut to the combination of the
+.Cm fetch
+and
+.Cm checkout
+subcommands.
+See
+.Cm fetch
+for the URI of the WAD repository from which WAD data is transferred and
+a list of available options.
+.It Cm push
+Transfers data from WAD files to the remote WAD repository.
+The remote URI is defined by the
+.Ev GIT_WAD_REMOTE_PUSH
+environment variable.
+The default setting is to transfer WAD file data for the entire HEAD
+history.
+.Pp
+The options are as follows:
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl 1
+Transfers only WAD file data for the HEAD not its history, i.e. it
+transfers neither their previous version nor the contents of WAD files
+that are no longer referenced.
+.It Fl a
+Transfers all versions of WAD files referenced in the complete
+repository history, i.e. in all commits of all branches.
+.El
+.It Cm status
+Displays resolved, unrestored and orphaned WAD files for the current
+HEAD commit.
+The first are WAD files ready for use; the second are WAD
+files whose data is transferred locally but whose contents have yet to
+be restored
+.Pq see Cm checkout ;
+the third are WAD files whose data must be transferred locally before
+their contents can be restored
+.Pq see Cm pull .
+.Pp
+The initialisation status is also displayed
+.Pq see Cm init ,
+as well as the number of WAD file data that can be removed locally
+.Pq see Cm prune .
+.Pp
+The options are those of the
+.Cm prune
+subcommand and affect the reported number of WAD file data to remove.
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev GIT_WAD_REMOTE_FETCH
+URI of the remote repository
+.Em from
+which WAD file data is transfered.
+By default it is set to the
+.Ev GIT_WAD_REMOTE_PUSH
+environment variable.
+.It Ev GIT_WAD_REMOTE_PUSH
+URI of the remote repository
+.Em to
+which WAD file data is transfered.
+.El
+.Sh FILES
+.Bl -tag -width Ds
+.It Pa .git_wad.cfg
+File at the root of the working tree in which environment variables
+controlling
+.Nm
+can be overwritten
+.Pq see Sx ENVIRONMENT No section .
+This is a shell script whose syntax must respect the POSIX shell.
+Here's an example of how to define an SSH remote:
+.Bd -literal -offset Ds
+GIT_WAD_REMOTE_FETCH="user@remote:repo-wad.git"
+GIT_WAD_REMOTE_PUSH="user@remote:repo-wad.git"
+.Ed
+.It Pa .gitattributes
+Regular
+.Xr gitattributes 5
+file in which you define which files are to be managed by
+.Nm .
+To do this, simply add the
+.Li filter=wad
+attribute to these files.
+For example, to manage the
+.Pa test.png
+image and all
+pdf files with
+.Nm ,
+the following lines must be added to your
+.Pa .gitattributes :
+.Bd -literal -offset Ds
+test.png filter=wad
+*.pdf filter=wad
+.Ed
+.El
+.Sh EXIT STATUS
+.Ex -std
.Sh SEE ALSO
.Xr git 1
