Stefan Sperling <stsp@stsp.name> wrote:
> On Thu, Dec 28, 2023 at 06:17:05PM +0100, Benjamin Stürz wrote:
> > On 12/28/23 12:51, Benjamin Stürz wrote:
> > > I'll take a look into the code of got, and see if I can do something,
> > > if no one is already working on it.
> > Here's a patch implementing a WIP archive command.
> > There are still a few things to do,
> > like adding options and a section in the man page.
> > But I think it's ready for testing.
> > Most of the code is copied from the checkout command,
> > the rest is either written by me or stolen from a man page.
> 
> I am not sure about my overall end-goals for the design, and I do
> not have a lot of time to think about it now, but here are some
> quick thoughts:
> 
> The archive command could work with a packing list file that contains
> a list of files to include in archives. The file could be versioned in
> some fully automatic or semi-automatic way. It could be visible, under
> some well-known name such as got-archive.conf or got-archive-list.txt,
> or be hidden somewhere in meta-data.
> 
> If the command assumed an existing work tree as a starting point, rather
> than checking out an entire repository, then it could be more flexible.
> Consider multi-project repositories (fairly rare with Git, but they
> do exist) which could be checked out with a path-prefix via
> 'got checkout -p' to obtain the subtree of the repository that needs
> to be archived.
> 
> A mixed-commit work tree would be rejected with an error, similar to
> how some other commands already do it. Local modifications to versioned
> files that are not yet committed would be tolerated but perhaps shown
> to the user for verification. E.g. it would be OK to locally tweak
> the version string in a Makefile, but having some non-committed changes
> in the code or in the packing list would probably be bad.
> 
> One advantage of using an existing work tree and a packing list is
> that invoking the command could potentially become as simple as
> running something like this in a work tree:
> 
>   got archive got-0.96.tar.gz

I think this is on the right track. See `fossil tarball`[0] for prior
art that I once used often (nowadays I mostly use tar with a make
recipe) and which does it like this but takes a required positional
<version> argument:

  fossil tarball <version> <filepath>

Where <version> is a reference of some sort (e.g., hash, branchname).
The version aspect can be handy when the desired tarball comprises no
untracked files, but if such a thing were wanted in got, the -c flag
would make a better fit:

  got archive -c <commit> filepath

Then we could use tags, keywords, branches, etc. to specify the version
for the archive, albeit as an optional flag--not a required operand.
When -c is omitted, the work tree is used if in a work tree.

In that vein, fossil's tarball command has some other features that may
be useful such as globbing to ignore or include files, and the `--name`
and `-R` options to specify the root dir in which the archive will be
extracted and to use a repository instead of a work tree. These might
make sense for got's archive command too; for example:

  got archive [-c commit] [-d dir] [-p plist] [-r repo] file

TBF, I am somewhat ambivalent about `got archive`: OT1H, I share naddy's
position insofar as archiving is better left for other tools; OTOH, I
used `fossil tarball` often and sometimes still do so I appreciate the
utility of such a tool. I just worry about adding features for things
that can already be done largely without friction. Perhaps having got
generate a list of files for tar(1) to use with -I would serve the same
usecase. But then you still need to checkout the version to have the
requisite files on disk, although maybe got could also do that in the
same command that generates the list of archive contents. But then you
still need to run tar. Whereas it is nice when the vcs provides all that
functionality in one command.

[0]: https://fossil-scm.org/home/help?cmd=tarball

> Version numbers are tricky. There are many conventions, your script
> already has a specific flag to deal with tag names that have a 'v'
> prefix, but this seems overly specific. Leaving the version entirely
> up to the user as a user-specified string might be the most general
> solution, rather than trying to be clever about it. Perhaps just let
> the version be a part of a user-specified archive name and leave it
> at that? I understand that your wrapper tool does its work based on
> tags in the repository but is it strictly necessary to integrate
> this new feature with tags so tightly? A wrapper script which checks
> out all tags and runs 'got archive' on each would still be possible.
> 
> Instead of fts_open(3) this feature could use the work tree status
> crawl to pick up the versioned and unversioned files to package.
> 
> I would prefer to ignore file types like fifos and device nodes.
> Such files should not appear in a reasonable source code tarball.
> Unless I am missing something, any file types other than regular
> files, directories, or symlinks would be out of the ordinary,
> wouldn't they? Besides, Git doesn't version such files either.
> 
> Writing the tar headers directly is clever and avoids having to
> run an external 'tar' program. I hope though that this won't run
> into subtle bugs that result in incompatibilities with some
> implementations of tar. The header looks simple enough but I do
> not have enough experience with the tar file format to judge this.
> 
> If a packing list doesn't exist yet then 'got archive' could create it
> based on the contents of the work tree. Users could then edit the list
> as needed. The list would contain both versioned and unversioned files
> that are expected to be present in the archive. It could also contain
> per-file annotations (like those used in OpenBSD's port tree's PLIST)
> in case that helps the design somehow.


-- 
Mark Jamsek <https://bsdbox.org>
GPG: F2FF 13DE 6A06 C471 CA80  E6E2 2930 DC66 86EE CF68