zimoun schreef op wo 05-01-2022 om 12:48 [+0100]:
> Well, I think ’#:recursive?’ is confusing, and ’auto’ too because it is
> not POLA for a plumbing function, IMHO.  [...]

Principle of least authority, or principle of least astonishment?
I presume the latter.

> Anyway. It is v4 and it is ready to merge. :-)

I vote for a purple bikeshed! But your orange bikeshed would also keep
the bikes out of the rain.

> I just propose to replace ’#:recursive?’ by ’#:nar-serializer?’ and a
> docstring along these lines,
> 
> --8<---------------cut here---------------start------------->8---
>   "Compute the hash of FILE with ALGORITHM.  If NAR-SERIALIZER? is
>   #true, compute the combined hash (NAR hash) of FILE for which (SELECT?
>   FILE STAT) returns true.
> 
>   If NAR-SERIALIZER? is #false, compute the regular hash using the
>   default serializer.  It is meant to be used for a regular file.
> 
>   If NAR-SERIALIZER? is 'auto', when FILE is a directory, compute the
>   combined hash (NAR hash).  When FILE is a regular file, compute the
>   regular hash using the default serializer.  The option ’auto’ is meant
>   to apply by default the expected hash computation.
> 
>   Symbolic links are not dereferenced unless NAR-SERIALIZER? is false.
> 
>   This procedure must only be used under controlled circumstances; the
>   detection of symbolic links in FILE is racy.
> --8<---------------cut here---------------end--------------->8---
> 
> WDYT?

The nar hash / regular hash difference seems a very low-level detail to
me, that most (all?) users don't need to be bothered about. Except
maybe if FILE denotes an executable regular file, but file-hash* is
currently only used on tarballs/zip files/git checkouts, which aren't
executable files unless weirdness or some kind of attack is happening.

I think that, the ‘least astonishing’ thing to do here, is computing
the hash that would go into the 'hash' / 'sha256' field of 'origin'
objects by default, and not the nar hash for regular files that's
almost never used.

Greetings,
Maxime.