#
#
# patch "monotone.texi"
#  from [3dd4a46b927188633e8d534b6dc9f6bef2c1c6f2]
#    to [3d8c5196889a958e75477bbf9bc4031938820dcb]
# 
# patch "selectors.cc"
#  from [c9398d4afe1fa2b32571548f786c7055f0801569]
#    to [a07e48ac1c801d6d0373f13288e821514f18c46f]
# 
# patch "tests/extended-selectors/__driver__.lua"
#  from [d5ed878a048a1966b23fa5e7413244ac785efd8f]
#    to [435f44fb1b33bdfb53929fe6bd15ba7fa4c2c1d3]
#
============================================================
--- monotone.texi	3dd4a46b927188633e8d534b6dc9f6bef2c1c6f2
+++ monotone.texi	3d8c5196889a958e75477bbf9bc4031938820dcb
@@ -2940,6 +2940,11 @@ @heading Composite selectors
 For example, @code{children(m:*foobar*)} would return the children of any
 revisions which have @code{comment} or @code{changelog} certs containing the
 word @code{foobar}.
address@hidden pick(A)
+Picks one of the revisions selected by @code{A}, and returns that. For example,
address@hidden:some-branch} is often used with @code{mtn update}, but will fail if
address@hidden has multiple heads. Using @code{pick(h:some-branch)} instead
+will always choose a single head, and not fail if there is more than one.
 @end table
 
 @heading Selector expansion
============================================================
--- selectors.cc	c9398d4afe1fa2b32571548f786c7055f0801569
+++ selectors.cc	a07e48ac1c801d6d0373f13288e821514f18c46f
@@ -560,6 +560,16 @@ public:
         ret.erase(revision_id());
         return ret;
       }
+    else if (name == "pick")
+      {
+        E(args.size() == 1, origin::user,
+          F("the 'pick' function takes 1 argument, not %d") % args.size());
+        set<revision_id> tmp = args[0]->complete(project);
+        set<revision_id> ret;
+        if (!tmp.empty())
+          ret.insert(*tmp.begin());
+        return ret;
+      }
     else
       {
         E(false, origin::user,
============================================================
--- tests/extended-selectors/__driver__.lua	d5ed878a048a1966b23fa5e7413244ac785efd8f
+++ tests/extended-selectors/__driver__.lua	435f44fb1b33bdfb53929fe6bd15ba7fa4c2c1d3
@@ -90,3 +90,13 @@ expect("lca(h:testbranch;h:otherbranch)"
 other_head = merge(other_2, m, "otherbranch", "Jack")
 expect("max((ancestors(h:testbranch)|h:testbranch)/(ancestors(h:otherbranch)|h:otherbranch))", m)
 expect("lca(h:testbranch;h:otherbranch)", m)
+
+
+check(mtn("automate", "select", "pick(h:*)"), 0, true, nil)
+numlines = 0
+for line in io.lines("stdout")
+do
+   numlines = numlines + 1
+   check(line == m or line == other_2)
+end
+check(numlines == 1)