f7a410eca9 2008-10-18       drh: From: "Ralf S. Engelschall"
f7a410eca9 2008-10-18       drh: Date: October 18, 2008 1:40:53 PM EDT
f7a410eca9 2008-10-18       drh: To: drh@hwaci.com
f7a410eca9 2008-10-18       drh: Subject: Some Fossil Feedback
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: I've today looked at your Fossil project (latest version from your
f7a410eca9 2008-10-18       drh: repository). That's a _really_ interesting and very promising DVCS.
f7a410eca9 2008-10-18       drh: While I looked around and tested it, I stumbled over some issues I want
f7a410eca9 2008-10-18       drh: to share with you:
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o No tarball
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  You currently still do not provide any tarballs of the Fossil sources.
f7a410eca9 2008-10-18       drh:  Sure, you are still hacking wild on the code and one can on-the-fly
f7a410eca9 2008-10-18       drh:  fetch a ZIP archive, but that's a manual process. For packagers (like
f7a410eca9 2008-10-18       drh:  me in the OpenPKG project) this is very nasty and just means that
f7a410eca9 2008-10-18       drh:  Fossil will usually still not be packaged. As a result it will be not
f7a410eca9 2008-10-18       drh:  spreaded as much as possible and this way you still do not get as much
f7a410eca9 2008-10-18       drh:  as possible feedback. Hence, I recommend that you let daily snapshot
f7a410eca9 2008-10-18       drh:  tarballs (or ZIP files) be rolled. This would be great.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o UUID
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  Under http://www.fossil-scm.org/index.html/doc/tip/www/concepts.wiki
f7a410eca9 2008-10-18       drh:  you describe the concepts and you clearly name the artifact ID a
f7a410eca9 2008-10-18       drh:  "UUID" and even say that this is a "Universally Unique Identifier".
f7a410eca9 2008-10-18       drh:  Unfortunately, a UUID is a 128-bit entity standardized by the ISO
f7a410eca9 2008-10-18       drh:  (under ISO/IEC 11578:1996) and IETF (under RFC-4122) and hence it is
f7a410eca9 2008-10-18       drh:  *VERY MUCH* confusing and unclean that your 160-bit SHA1-based ID is
f7a410eca9 2008-10-18       drh:  called "UUID" in Fossil.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  I *STRONGLY* recommend you to either use real UUIDs (128-bit
f7a410eca9 2008-10-18       drh:  entities, where a UUID of version 5 even is SHA1-based!) or you name
f7a410eca9 2008-10-18       drh:  your 160-bit SHA1 entities differently (perhaps AID for "Artifact
f7a410eca9 2008-10-18       drh:  Identifier"?).
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "fossil cgi <script>"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  Currently we have only "fossil cgi <script>" where <script> contains
f7a410eca9 2008-10-18       drh:  "repository: <file>". This is a neat idea and should be kept. But
f7a410eca9 2008-10-18       drh:  this way one cannot easily host multiple repositories over this
f7a410eca9 2008-10-18       drh:  CGI interface without creating such a script for every individual
f7a410eca9 2008-10-18       drh:  repository.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  Perhaps a "fossil cgi --repository <file>" would help here, as this
f7a410eca9 2008-10-18       drh:  way one can use a generic CGI script which first figures out the
f7a410eca9 2008-10-18       drh:  name <name> of the individual project and then runs "fossil cgi
f7a410eca9 2008-10-18       drh:  --repository /path/to/repositories/<name>.db". But perhaps I'm just
f7a410eca9 2008-10-18       drh:  overlooking something and this is already possible...
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "fossil db <operation>"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  In Monotone DVCS we have a "mtn db" command for the low-level SQLite
f7a410eca9 2008-10-18       drh:  database manipulations. For instance a "mtn --db=<monotone-repository>
f7a410eca9 2008-10-18       drh:  db dump" is more or less equal to a "sqlite3 <monotone-repository>
f7a410eca9 2008-10-18       drh:  .dump". A "mtn --db=<monotone-repository> db exec '<SQL>'" is equal
f7a410eca9 2008-10-18       drh:  "echo '<SQL>' | sqlite3 <monotone-repository>", etc. The point is
f7a410eca9 2008-10-18       drh:  that the DVCS user usually has no SQLite CLI at hand but as the DVCS
f7a410eca9 2008-10-18       drh:  already contains more or less the complete SQLite it is very useful to
f7a410eca9 2008-10-18       drh:  also include the SQLite CLI functionality and wire it into the DVCS
f7a410eca9 2008-10-18       drh:  CLI via a "db" command.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "fossil version"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  Mostly all VCS I know if either support a command "version" or a
f7a410eca9 2008-10-18       drh:  command-line option "--version" or most of the time even both. Please
f7a410eca9 2008-10-18       drh:  output the "This is fossil version [9e80dc66cf] 2008-10-18 13:03:36"
f7a410eca9 2008-10-18       drh:  there (at least additionally) instead of at the end of "fossil help".
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "--port" vs. "-port"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  In the "fossil help server" there is "--port" while under
f7a410eca9 2008-10-18       drh:  http://www.fossil-scm.org/index.html/doc/tip/www/quickstart.wiki there
f7a410eca9 2008-10-18       drh:  is "-port". I personally like GNU-long-style options "--xxxx" more
f7a410eca9 2008-10-18       drh:  than the CC-style options "-xxx". But anyway, independent which one is
f7a410eca9 2008-10-18       drh:  correct (well, perhaps both even work) only one should be documented
f7a410eca9 2008-10-18       drh:  to avoid confusion.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o User creation on the CLI
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  There is "fossil user new ?USERNAME?" which interactively prompts
f7a410eca9 2008-10-18       drh:  for the capabilities and the password -- even from the TTY and not
f7a410eca9 2008-10-18       drh:  from STDIN. One needs "fossil user new ?USERNAME? ?CAPABILITIES?
f7a410eca9 2008-10-18       drh:  ?PASSWORD?" to be able to create a repository in batch without having
f7a410eca9 2008-10-18       drh:  to hack the user into the "user" table via the SQLite CLI. Similar:
f7a410eca9 2008-10-18       drh:  the "fossil user password USERNAME" should be actually "fossil user
f7a410eca9 2008-10-18       drh:  password USERNAME ?PASSWORD?", please.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "-R <repository"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  There is the "-R" option for specifiying the repository. But it is
f7a410eca9 2008-10-18       drh:  a sub-command option and not a global option. And on "fossil ui" or
f7a410eca9 2008-10-18       drh:  "fossil server" it even is an argument and not an option. This is
f7a410eca9 2008-10-18       drh:  confusing. Every time one has to figure out how to set the repository
f7a410eca9 2008-10-18       drh:  on the CLI. Monotone simply uses a *global* option "--db" and that's
f7a410eca9 2008-10-18       drh:  it. So, I recommend that Fossil also uses a single global option
f7a410eca9 2008-10-18       drh:  "--repository"/"-R" instead of a command-specific option. Sure, not
f7a410eca9 2008-10-18       drh:  all commands might require a repository, but IMHO it is better to
f7a410eca9 2008-10-18       drh:  ignore the global option there than having to figure out every time
f7a410eca9 2008-10-18       drh:  how the repository has to be specified.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o Setup pages
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  When hitting "Apply changes" on any setup page, one keeps staying on
f7a410eca9 2008-10-18       drh:  this page. Sure, that's what an "apply" button usually is about. But
f7a410eca9 2008-10-18       drh:  I at least would have liked to see a button (either instead of the
f7a410eca9 2008-10-18       drh:  "apply changes" or at least in addition) which applies the changes and
f7a410eca9 2008-10-18       drh:  goes back to the setup main page (from where one usually come).
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o _FOSSIL_
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:   Very nice idea to use another SQLite database for the _FOSSIL_
f7a410eca9 2008-10-18       drh:   control file. BUT: Why "_FOSSIL_"? CVS's "CVS" directory was ugly for
f7a410eca9 2008-10-18       drh:   decades. Today we have ".svn", ".git", ".hg" and "_MTN"/".mtn" to get
f7a410eca9 2008-10-18       drh:   rid of those ugly control files or directories of the DVCS! Sure,
f7a410eca9 2008-10-18       drh:   dot-files are disliked by Windows people. But that's no problem, one
f7a410eca9 2008-10-18       drh:   can accept "_XXX" in addition to ".XXX" easily, of course.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:   So, I really would like to see the file "_FOSSIL_" to be renamed
f7a410eca9 2008-10-18       drh:   to ".fossil" under Unix and "_fossil" under Windows or (if the
f7a410eca9 2008-10-18       drh:   upper-case is important to you) ".FOSSIL" and "_FOSSIL". But to see
f7a410eca9 2008-10-18       drh:   an ugly "_FOSSIL_" at the top of every source tree is really rather
f7a410eca9 2008-10-18       drh:   boring for Unix people!
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "fossil open", "fossil checkout", "fossil update".
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  I'm personally confused that "fossil open" is what "checkout" does in
f7a410eca9 2008-10-18       drh:  other DVCS and that "checkout" is just a variant of "update". Hmmm...
f7a410eca9 2008-10-18       drh:  for me it looks at least one should be eleminated to reduce confusion.
f7a410eca9 2008-10-18       drh:  The difference between checkout and update could become an option of
f7a410eca9 2008-10-18       drh:  a single option. And the remaining to perhaps better should be either
f7a410eca9 2008-10-18       drh:  "open" + "update" or "checkout" + "update". Well, perhaps I'm still
f7a410eca9 2008-10-18       drh:  not understanding Fossil enough. But I can only tell that I got rather
f7a410eca9 2008-10-18       drh:  confused.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "fossil commit"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  There is "fossil commit" but no short-hand "fossil ci". But there
f7a410eca9 2008-10-18       drh:  is "fossil status" and even just "fossil st" which clearly shows
f7a410eca9 2008-10-18       drh:  that Fossil allows abbreviations or at least prefix-matching on the
f7a410eca9 2008-10-18       drh:  commands. Sure, "ci" is not a prefix of "commit" but mostly all VCS
f7a410eca9 2008-10-18       drh:  support the good old RCS/CVS "ci" and similar aliases. So I recommend
f7a410eca9 2008-10-18       drh:  that Fossil does not only alias matching, but also provides aliases:
f7a410eca9 2008-10-18       drh:  "ci" for "commit", "co" for "checkout", "log" for "timeline", etc.
f7a410eca9 2008-10-18       drh:  Sorry, having to type the long "fossil commit" every time is too long
f7a410eca9 2008-10-18       drh:  for us Unix hackers ;-)
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  Additionally, Fossil seems to use GnuPG when installed and --nosign is
f7a410eca9 2008-10-18       drh:  not specified. Hmm... two questions arise here for me: 1. should the
f7a410eca9 2008-10-18       drh:  use of a cryptographically strong signature really be just _optional_
f7a410eca9 2008-10-18       drh:  (Monotone for instance RSA signs every commit) and 2. is GnuPG here
f7a410eca9 2008-10-18       drh:  really the right tool (Monotone does a plain RSA signing and is even
f7a410eca9 2008-10-18       drh:  able to leverage a running SSH agent for the operation -- something
f7a410eca9 2008-10-18       drh:  which is very cool both under Unix with "ssh-agent" and under Windows
f7a410eca9 2008-10-18       drh:  with "pagent"). OTOH, GnuPG 2.x supports a gpg-agent, so this might be
f7a410eca9 2008-10-18       drh:  no longer a big issue. But Fossil should document this a little bit
f7a410eca9 2008-10-18       drh:  futher: how to create the necessary GnuPG key, how to setup gpg-agent,
f7a410eca9 2008-10-18       drh:  etc.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "fossil diff"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  There is "Usage: fossil diff|gdiff ?-i? ?-r REVISION? FILE...". Two
f7a410eca9 2008-10-18       drh:  questions arise: Why do I have to specify a "FILE"? I would expect
f7a410eca9 2008-10-18       drh:  that a simple "fossil diff" recursively shows a "diff" of all changed
f7a410eca9 2008-10-18       drh:  files in the source tree. Additionally, how does one do a diff between
f7a410eca9 2008-10-18       drh:  two particular revisions (one seems to be not able to specifiy "-r"
f7a410eca9 2008-10-18       drh:  twice).
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "manifest" / "manifest.uuid"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  Above I was already bothered by the _FOSSIL_ file, but now that I
f7a410eca9 2008-10-18       drh:  played with Fossil I see that "manifest" and "manifest.uuid" files
f7a410eca9 2008-10-18       drh:  showed up in my source tree. Why is this not implicitly in the
f7a410eca9 2008-10-18       drh:  database and instead externally represented in the source tree.
f7a410eca9 2008-10-18       drh:  Hmmm... then I recommend that you use a .fossil *DIRECTORY*, place
f7a410eca9 2008-10-18       drh:  the control file into .fossil/control (or whatever) and the manifest
f7a410eca9 2008-10-18       drh:  stuff into .fossil/manifest and .fossil/manifest.uuid. But please do
f7a410eca9 2008-10-18       drh:  not clutter the top-level of the source three with control data of the
f7a410eca9 2008-10-18       drh:  DVCS.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "fossil mv"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  There is "fossil add" and "fossil rm", but no "fossil mv". Hopefully
f7a410eca9 2008-10-18       drh:  this doesn't mean a file move is an "add" and a "remove" bundle, as
f7a410eca9 2008-10-18       drh:  this way Fossil would have trouble to know that the file was renamed
f7a410eca9 2008-10-18       drh:  and hence the full history tracking of a file seems to be broken.
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: o "fossil changes" vs. "fossil status"
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh:  Finally, I got confused by the "fossil changes" and "fossil status"
f7a410eca9 2008-10-18       drh:  commands. "fossil status" seems to be a super-set of "fossil changes".
f7a410eca9 2008-10-18       drh:  Looks a little bit less orthogonal than necessary. I would remove
f7a410eca9 2008-10-18       drh:  "fossil changes" or at least do not show the file details on "fossil
f7a410eca9 2008-10-18       drh:  status".
f7a410eca9 2008-10-18       drh: 
f7a410eca9 2008-10-18       drh: Yours,
f7a410eca9 2008-10-18       drh:                                       Ralf S. Engelschall
f7a410eca9 2008-10-18       drh: