Patchwork D1380: dirstate: document dirstatemap interface

login
register
mail settings
Submitter phabricator
Date Nov. 13, 2017, 12:18 p.m.
Message ID <differential-rev-PHID-DREV-27vrwjtxjs5za3oyeoaz-req@phab.mercurial-scm.org>
Download mbox | patch
Permalink /patch/25519/
State Superseded
Headers show

Comments

phabricator - Nov. 13, 2017, 12:18 p.m.
mbthomas created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D1380

AFFECTED FILES
  mercurial/dirstate.py

CHANGE DETAILS




To: mbthomas, #hg-reviewers
Cc: mercurial-devel
phabricator - Nov. 13, 2017, 10:41 p.m.
durin42 requested changes to this revision.
durin42 added inline comments.
This revision now requires changes to proceed.

INLINE COMMENTS

> dirstate.py:1198
>  class dirstatemap(object):
> +    '''
> +    Dirstate contents

Nit: let's try and prefer """ to '''

Try and get a pithy one-line summary of the class on the first line of the docstring with the """

> dirstate.py:1214
> +
> +    - `copymap` is a dict mapping filenames to the filename they were copied
> +      from.

`copymap` maps destination filenames to their source filename

perhaps? either way, optional.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D1380

To: mbthomas, #hg-reviewers, durin42
Cc: durin42, mercurial-devel
phabricator - Nov. 14, 2017, 7:19 p.m.
mbthomas added inline comments.

INLINE COMMENTS

> durin42 wrote in dirstate.py:1198
> Nit: let's try and prefer """ to '''
> 
> Try and get a pithy one-line summary of the class on the first line of the docstring with the """

Sure.  This file uses a mix of `"""` and `'''` and I couldn't tell which was preferred.

REPOSITORY
  rHG Mercurial

REVISION DETAIL
  https://phab.mercurial-scm.org/D1380

To: mbthomas, #hg-reviewers, durin42
Cc: durin42, mercurial-devel

Patch

diff --git a/mercurial/dirstate.py b/mercurial/dirstate.py
--- a/mercurial/dirstate.py
+++ b/mercurial/dirstate.py
@@ -127,8 +127,7 @@ 
 
     @propertycache
     def _map(self):
-        '''Return the dirstate contents as a map from filename to
-        (state, mode, size, time).'''
+        '''Return the dirstate contents (see documentation for dirstatemap).'''
         self._map = dirstatemap(self._ui, self._opener, self._root)
         return self._map
 
@@ -1196,6 +1195,46 @@ 
         self._opener.unlink(backupname)
 
 class dirstatemap(object):
+    '''
+    Dirstate contents
+
+    The dirstate contains the following state:
+
+    - `identity` is the identity of the dirstate file, which can be used to
+      detect when changes have occurred to the dirstate file.
+
+    - `parents` is a pair containing the parents of the working copy. The
+      parents are updated by calling `setparents`.
+
+    - the state map maps filenames to tuples of (state, mode, size, mtime),
+      where state is a single character representing 'normal', 'added',
+      'removed', or 'merged'. It is accessed by treating the dirstate as a
+      dict.
+
+    - `copymap` is a dict mapping filenames to the filename they were copied
+      from.
+
+    The dirstate also provides the following views onto the state:
+
+    - `nonnormalset` is a set of the filenames that have state other
+      than 'normal', or are normal but have an mtime of -1 ('normallookup').
+
+    - `otherparentset` is a set of the filenames that are marked as coming
+      from the second parent when the dirstate is currently being merged.
+
+    - `dirs` is a set-like object containing all the directories that contain
+      files in the dirstate, excluding any files that are marked as removed.
+
+    - `filefoldmap` is a dict mapping normalized filenames to the denormalized
+      form that they appear as in the dirstate.
+
+    - `dirfoldmap` is a dict mapping normalized directory names to the
+      denormalized form that they appear as in the dirstate.
+
+    Once instantiated, the nonnormalset, otherparentset, dirs, filefoldmap and
+    dirfoldmap views must be maintained by the caller.
+    '''
+
     def __init__(self, ui, opener, root):
         self._ui = ui
         self._opener = opener