Category: monotone

Tony Cooper just released a new version of mtn-browse – a monotone database browser, which comes with a couple of bug fixes and a small enhancement with respect to remote server usage.

Check out the NEWS file for a complete list of changes and grab your copy here.

As I promised earlier I’ll continue my little series of noteworthy changes and additions in the upcoming monotone release. What I’ll blog about today may sound as if it is merely “syntactic” sugar for the command line end user, but serves a greater purpose when its put in perspective: The introduction of overwritable and negatable options.

Lets start with a simple example: monotone creates a special type of certs if a user explicitely calls the `suspend` command to mark a particular branch – actually its head revision(s) – as end-of-life, or uninteresting. This is useful in case a certain feature branch has been merged back into the main branch and the feature branch name should no longer confuse other people. Since monotone cannot physically delete these no longer needed data due to its distributed nature, the internal revision machinery now simply ignores branches and revisions which have these kind of certs and basically hides them from the user, so they aren’t picked as update candidates when `update` is called and they also no longer show up in the list of branches (`list branches`).

Of course people might still want to see at some point of time what suspended branches are actually available, sometimes maybe to revive a dead development line or for other historical purposes. For this use case monotone has a global option `–ignore-suspend-certs`, which simply deactivates the automatic hiding and all commands behave as if no suspend certs exist at all. So long so good, but there was a nitty gritty use case problem with this (and other similar) functionality:

If a user permanently decided to ignore suspend certs, for example by adding a specific section in his global `get_default_command_options`, he could not easily deactivate or overwrite this setting again via command line. The same applied to long-running processes, like `automate stdio`: once a client triggered the list branches command there with the `–ignore-suspend-certs` option, the client was unable to switch this flag off in case he wanted to query only active branches with the next invocation.

Up until 0.48 only ugly workarounds existed, such as restarting the stdio process, deactivating the loading of hooks or temporarily commenting out the particular section in the lua file, but with the recent merge of the options branch, it became possible. Every revertable, boolean flag gained a corresponding cancel flag, which is most of the time just named `–no-`:

$ mtn ls branches --ignore-suspend-certs --no-ignore-suspend-certs

(Can you guess what this command will now actually do? Little hint: The last occurrence counts…)

But as I mentioned above, this is only half of the truth: Not all cancel flags are just prefixed with a “no-“, in some cases they also look completly different and in some cases they even made us rename the original option, to keep the flow of the UI syntax and to prevent the invention of ugly pseudo options (or do you think `–no-norc` is a good name for the cancel option of `–norc`?).

Before you scream “Oh my god, will I ever get used to this new options?! You broke monotone for me!” let me give you a few words of relief:

1. For common options which have been changed or removed, there is a new deprecation functionality which points you at the new option syntax.
2. monotone’s inline command help will not only show you the full syntax of the original option, but also of the cancel option name.
3. Just as partial command names are completed, option names are now completed as well. If a certain prefix has multiple expansions, all possible options are listed with a short description. (For my little example above, the smallest unique prefix for the long `–ignore-suspend-certs` option is `–ignore-`, as there is also an option named `–ignored` available, for a completely different use case though.)
4. Finally, if you’re still puzzled by all the new and changed options and general calling syntax and you want a single page which you can just skim / search over for the thing you’re looking for, I’m pleased to tell you that the next monotone version will again have a manual page, but this time its auto-generated from the internal command tree and options. Maybe I’ll tell you a little bit more about this in one of the next blog posts, if not, just try it out with `mtn manpage` as soon as 0.99 hits the streets.

I hope we’ll get a lot of feedback on this for the 0.99 release, as I firmly believe that this overhaul will make the functional and consistent foundations of monotone even stronger.

I also hope that we do not scare too many people away; we did this with purpose for 0.99 and not 1.0 or 1.1, so trust me, we don’t plan to mess around with the UI to this extent again anytime soon 🙂

Thanks for reading so far. Your comments are welcome on irc and via mail.

There was only one hook in monotone until now which could be “reused” to interact with the commit process and validate the changeset that should be committed, the `validate_commit_message` hook. But this was a bit clumsy as it was actually designed to validate the commit message (as the name suggests) and not the changeset, thus the hook was called _after_ the commit message was entered in the editor (or was given with `–message` or `–message-file`).

Now monotone (from 0.99 onwards) gained a new commit hook which is called before the commit message processing takes place, but after the logic validated the changeset and branch to which it should be committed. Its named simply `validate_changes` and takes two parameters, the revision to be committed as full text (parsable in the hook via `parse_basic_io`) as the first and the name of the branch to which the revision should be committed as the second. Just as `validate_commit_message`, it is expected to return a tupel containing a boolean which denotes if the change is valid or not and an optional string which explains the reason if not and which is displayed to the committer afterwards.

With this new installment, it should feel natural e.g. to create a pre-commit hook which ensures that none of the patched or added sources contains Windows line endings:

function validate_changes(revdata, branchname)
  local parsed = parse_basic_io(revdata)
  for _,stanza in ipairs(parsed) do
    if stanza.name == "add_file" or
       stanza.name == "patch" then
      local file = stanza.values[1]
      if not guess_binary_file_contents(file) then
        local fp = assert(io.open(file, "r"))
        local contents = fp:read("*all")
        fp:close()
        if string.find(contents, "\r\n") then
          return false, "CRLF detected"
        end
      end
    end
  end
  return true, ""
end

Unfortunately its not yet possible to call `mtn_automate`, the lua interface to monotone’s automation commands, from hooks like this. Then we could have saved the `read(“*all”)` call and would only have to scan the output of `automate content_diff`, which should be a little faster than doing a full string search in lua for bigger files. We, i.e. the monotone devs, are aware of the problem though and will come up with a solution sooner or later.

I hope this new hook will still be useful for some of you until then.