# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@fb.com>
# Date 1432846913 25200
# Node ID ae38370fe2822c80c80434592d94ec23dea061ec
# Parent  d0f1d8b4de57a4a8c7be90fa5c5bb7d3afc88c44
pull: document the race condition with bookmark name

It seems valuable to document this in-place to help the next poor soul
looking at this code to understand what kind of beast he is currently
facing.

diff -r d0f1d8b4de57 -r ae38370fe282 mercurial/commands.py
--- a/mercurial/commands.py	Thu May 28 13:55:03 2015 -0700
+++ b/mercurial/commands.py	Thu May 28 14:01:53 2015 -0700
@@ -5123,6 +5123,10 @@
         if opts.get('bookmark'):
             if not revs:
                 revs = []
+            # The list of bookmark used here is not the one used to actually
+            # update the bookmark name. This can result in the revision pulled
+            # not ending up with the name of the bookmark because of a race
+            # condition on the server. (See issue 4689 for details)
             remotebookmarks = other.listkeys('bookmarks')
             for b in opts['bookmark']:
                 if b not in remotebookmarks:
@@ -5131,6 +5135,9 @@
 
         if revs:
             try:
+                # When 'rev' is a bookmark name, we cannot guarantee that it
+                # will be updated with that name because of a race condition
+                # server side. (See issue 4689 for details)
                 revs = [other.lookup(rev) for rev in revs]
             except error.CapabilityError:
                 err = _("other repository doesn't support revision lookup, "