3.3.1  Helper Tools

3.3.1.1  Extra Buttons

There are a number of extra buttons in this mode that do the following:

Button

Description

Runs the query entered into the Search term combobox entry field.

Stops the currently running query. This is very useful when you make a mistake and accidentally enter a valid query that returns many hundreds of matches.

Enters the currently selected selector term into the Search term combobox entry field.

3.3.1.2  Selector Terms

The part of the window shown below is solely dedicated to helping the user to enter valid selector terms. If you are familiar with Monotone's query syntax then you can simply enter the query directly into the Search term combobox entry field.

Figure 3-4  Selector Term Helper

The selector term combobox, the combobox that has Author showing in the above figure, has the following values:

  • Author - This selector allows one to select revisions based upon their author. This is Monotone's a: selector. It takes one parameter, the name of an author, normally in the form of an email address (but this does depend upon your naming conventions).

  • Branch - This selector allows one to select revisions based upon which branches they belong to. This is Monotone's b: selector. It takes one parameter, the name of a branch, normally in the form of a full qualified reverse DNS style project path (but again this does depend upon your naming conventions).

  • Cert - This selector allows one to select revisions based upon whether they have a particular certificate. This is Monotone's c: selector. It takes one parameter, the name of a Monotone certificate.

  • Date (=) - This selector allows one to select revisions based upon their creation date. This is Monotone's d: selector. It takes one parameter, the date and time to be compared against.

  • Date (<=) - This selector allows one to select revisions based upon whether their creation date is less than or equal to the specified date. This is Monotone's e: selector. It takes one parameter, the date and time to be compared against.

  • Date (>) - This selector allows one to select revisions based upon whether their creation date is greater than the specified date. This is Monotone's l: selector. It takes one parameter, the date and time to be compared against.

  • Head Revision - This selector allows one to select revisions based upon whether they are the head revision of the specified branch. This is Monotone's h: selector. It takes one parameter, the name of a branch. If the branch name is not specified then the branch in the current workspace is assumed.

  • Identifier - This selector allows one to select revisions based upon their revision id. This is Monotone's i: selector. It takes one parameter, the id of a revision, in the form of a hexadecimal string. The revision id need not be complete.

  • Key - This selector allows one to select revisions based upon whether at least one of their certificates has been signed by the specified key. This is Monotone's k: selector. It takes one parameter, the key, in the form of either its given name, its local name or its full hexadecimal hash id.

  • Logical And - This is a logical AND operator. This is Monotone's / selector operator. It takes no parameters but instead combines two other selectors together.

  • Logical Or - This is a logical OR operator. This is Monotone's | selector operator. It takes no parameters but instead combines two other selectors together.

  • Message - This selector allows one to select revisions based upon whether their changelog or comment certificates contain certain text phrases. This is Monotone's m: selector. It takes one parameter, the text that is to be matched, with * being a wildcard character.

  • Parent - This selector allows one to select revisions that are parents of the specified revision id. This is Monotone's p: selector. It takes one parameter, the id of a revision, in the form of a hexadecimal string. The revision id need not be complete.

  • Tag - This selector allows one to select revisions based upon whether they are tagged with a particular tag. This is Monotone's t: selector. It takes one parameter, the name of a tag.

  • ancestors() - This composite selector allows one to select all revisions that are ancestors of the revisions that match the specified selector. It takes one parameter, a revision selector.

  • children() - This composite selector allows one to select all revisions that are children of the revisions that match the specified selector. It takes one parameter, a revision selector.

  • descendants() - This composite selector allows one to select all revisions that are descendants of the revisions that match the specified selector. It takes one parameter, a revision selector.

  • difference() - This composite selector allows one to select all revisions that match the first selector but not the second. It takes two parameters, both of which are revision selectors.

  • lca() - This composite selector allows one to select the revision that is the least or youngest common ancestor of the revisions that match the two selectors. This composite selector would typically be used to find either the last propagation point between two branches or the original branch point if no propagation had been done yet. It takes two parameters, both of which are revision selectors.

  • max() - This composite selector allows one to select all revisions that match the specified selector but are not themselves ancestors of other revisions that match that same selector. In effect this composite selector selects the youngest revision on each branch or fork in the revision history specified by the selector. It takes one parameter, a revision selector.

  • parents() - This composite selector allows one to select all revisions that are parents of the revisions that match the specified selector. It takes one parameter, a revision selector.

  • pick() - This composite selector allows one to select a single revision from the revisions that match the specified selector. One cannot determine the revision it picks, but it would typically be used when the operation concerned insists on having a single revision (for example, attempting to select the head revision on a branch that may have more than one head due to a divergence). It takes one parameter, a revision selector.

  1. If no argument is given to a selector term when it is inserted into the search term, then a comment will be inserted. This should be replaced with the actual argument or removed if the argument is optional.

  2. When inserting dates and times into a search term, one can remove the time field if you wish to. For example, Monotone will accept 2009-02-22T16:47:00, 2009-02-22, 2009-02 and 2009 as valid date/time values.

  3. Monotone's u: selector is not supported by Monotone Browser as it can only be used from within a Monotone workspace, which are largely ignored by this application.

  4. Some of the selectors mentioned above may not be available to you from the selector term combobox, as only those supported by your version of Monotone are listed.