From: "W. Trevor King" <wking@tremily.us>
To: notmuch@notmuchmail.org
Subject: [PATCH] NEWS: Document "nmbug: Translate to Python"
Date: Sun,  5 Oct 2014 08:47:21 -0700
Message-Id:
 <30987ac1951b6703839d1ec8546c91f2e94935ac.1412523971.git.wking@tremily.us>
Cc: Tomi Ollila <tomi.ollila@iki.fi>, David Bremner <bremner@debian.org>
Precedence: list

This is mostly culled from the commit message for 7f2cb3be (nmbug:
Translate to Python, 2014-10-03).  I realized while writing it that
the 7f2cb3be commit message has:

  * 'nmbug log' now execs 'git log', as there's no need to keep the
    Python process around once we've launched Git there.

But we dropped that exec in favor of the subprocess approach between
v3 and v4, I just forgot to update the commit message [1].

[1]: id:e630b6763e9d0771718afee41ea15b29bb4a1de8.1409935538.git.wking@tremily.us
     http://article.gmane.org/gmane.mail.notmuch.general/19007
---
 NEWS | 48 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/NEWS b/NEWS
index fa57e5d..c111dd0 100644
--- a/NEWS
+++ b/NEWS
@@ -22,6 +22,54 @@ Library changes
 Add return status to notmuch_database_close and
 notmuch_database_destroy
 
+nmbug
+-----
+
+The Perl script has been translated to Python; you'll need Python 2.7
+or anything from the 3.x line.  This gives us better control over
+subprocesses without resorting to third-party modules.  Most of the
+user-facing interface is the same, but there are a few changes, where
+reproducing the original interface was too difficult or we saw a
+change to make the underlying Git interface accessible:
+
+* 'nmbug help' has been split between the general 'nmbug --help' and
+  the command-specific 'nmbug COMMAND --help'.
+
+* Commands are no longer split into "most common", "other useful", and
+  "less common" sets.
+
+* 'nmbug commit' now only uses a single argument for the optional
+  commit-message text.
+
+* The default repository for 'nmbug push' and 'nmbug fetch' is now the
+  current branch's upstream (branch.<name>.remote) instead of
+  'origin'.  When we have to, we extract this remote by hand, but
+  where possible we just call the Git command without a repository
+  argument, and leave it to Git to figure out the default.
+
+* 'nmbug push' accepts multiple refspecs if you want to explicitly
+  specify what to push.  Otherwise, the refspec(s) pushed depend on
+  push.default.  The Perl version hardcoded 'master' as the pushed
+  refspec.
+
+* 'nmbug pull' defaults to the current branch's upstream
+  (branch.<name>.remote and branch.<name>.merge) instead of hardcoding
+  'origin' and 'master'.  It also supports multiple refspecs if for
+  some crazy reason you need an octopus merge (but mostly to avoid
+  breaking consistency with 'git pull').
+
+* 'nmbug status' now catches stderr, and doesn't print errors like:
+
+    No upstream configured for branch 'master'
+
+  The Perl implementation had just learned to avoid crashing on that
+  case, but wasn't yet catching the dying subprocess's stderr.
+
+* 'nmbug archive' now accepts positional arguments for the tree-ish
+  and additional 'git archive' options.  For example, you can run:
+
+    $ nmbug archive HEAD -- --format tar.gz
+
 nmbug-status
 ------------
 
-- 
2.1.0.60.g85f0837