# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@fb.com>
# Date 2014-09-29 03:18:43
# Node ID 7fdd1782fc4ee9da87d8af13e806dc9055db2c38
# Parent  1ddefcfcd3e6da10e44d3de094c9e4265c5c9deb

changelog: document the 'readpending' method

I happen to have spent some time understanding this logic, so I'm leaving
documentation for the next poor fellow.

diff --git a/mercurial/changelog.py b/mercurial/changelog.py
--- a/mercurial/changelog.py
+++ b/mercurial/changelog.py
@@ -259,6 +259,18 @@ class changelog(revlog.revlog):
         self.checkinlinesize(tr)
 
     def readpending(self, file):
+        """read index data from a "pending" file
+
+        During a transaction, the actual changeset data is already stored in the
+        main file, but not yet finalized in the on-disk index. Instead, a
+        "pending" index is written by the transaction logic. If this function
+        is running, we are likely in a subprocess invoked in a hook. The
+        subprocess is informed that it is within a transaction and needs to
+        access its content.
+
+        This function will read all the index data out of the pending file and
+        extend the main index."""
+
         if not self.opener.exists(file):
             return # no pending data for changelog
         r = revlog.revlog(self.opener, file)