9fc5c67c31ae — Steve Fink 3 months ago
[landed] update docs
2 files changed, 36 insertions(+), 1 deletions(-)

M README.md
M bin/landed
M README.md +28 -0
@@ 6,6 6,8 @@ These are tools that I think might be us
 
 Tools included:
 
+ - landed : Prune changesets that have landed, setting their successors to the landed
+   revisions.
  - get-taskcluster-logs : Retrieve groups of log files from a push by scraping taskcluster
  - json : Interactive navigation of a JSON file
  - debug : Start up a debugger within emacs on various types of files

          
@@ 46,6 48,32 @@ I use this via a symlink from ~/.hgrc.
 
 ----------------------------------------------------------------------
 
+landed - Prune patches that have landed, setting their successors to the landed
+revisions.
+
+Typical usage:
+
+    hg pull
+    landed
+
+That will look at the non-public (aka draft, probably) ancestors of your
+checked out revision, and scan for matching phabricator revisions (or commit
+messages, if phabricator revisions are not present) within the landed tree.
+You'll want to download the latest set of landed changes first, so they exist
+locally.
+
+You can also do this in a more targeted way:
+
+    landed -r 30deabdff172
+
+(or a revspec matching multiple patches).
+
+Note that this will not rebase any orphaned patches for you, so if you are
+pruning landed patches with descendants that have not yet been landed, you will
+need to rebase them (eg by running `hg evolve` or `hg evolve -a` or whatever.)
+
+----------------------------------------------------------------------
+
 get-taskcluster-logs - Retrieve groups of log files from a push by scraping taskcluster
 
 Typical example: copy link location to a taskcluster push (what you get from

          
M bin/landed +8 -1
@@ 24,6 24,10 @@ Take a set of draft revisions and find t
 output a command that prunes the given revisions, setting the landed
 equivalents as their successors.
 
+Changesets are matched up by the phabricator revision ID in their comments, if
+any. Otherwise, use the first line of their descriptions (with reviewer
+metadata stripped).
+
 The usual usage is to just run `landed` with no arguments from a directory
 based on a stack of patches, some of which have landed already. That will loop
 over all non-public ancestors and scan through mozilla-central to find patches

          
@@ 31,7 35,10 @@ with matching descriptions that have alr
 patches while setting their successors to their already-landed equivalents.
 
 More complex example: landed -r .^^^::. --user=sfink --branch=autoland
-'''
+
+Note that this will not rebase any orphaned patches for you, so if you are
+pruning landed patches that have not yet landed descendants, you will need to
+rebase them (eg by running `hg evolve` or `hg evolve -a` or whatever.) '''
 )
 
 DEFAULT_REVSET = "not public() and ancestors(.)"