Return-Path: <sshilovsky@gmail.com>
X-Original-To: notmuch@notmuchmail.org
Delivered-To: notmuch@notmuchmail.org
Received: from localhost (localhost [127.0.0.1])
	by olra.theworths.org (Postfix) with ESMTP id 0D192431FB6
	for <notmuch@notmuchmail.org>; Tue, 14 Oct 2014 07:50:34 -0700 (PDT)
X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
X-Spam-Flag: NO
X-Spam-Score: -0.799
X-Spam-Level: 
X-Spam-Status: No, score=-0.799 tagged_above=-999 required=5
	tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1,
	FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_LOW=-0.7] autolearn=disabled
Received: from olra.theworths.org ([127.0.0.1])
	by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)
	with ESMTP id 3Lx0KuvdZQNP for <notmuch@notmuchmail.org>;
	Tue, 14 Oct 2014 07:50:29 -0700 (PDT)
Received: from mail-lb0-f172.google.com (mail-lb0-f172.google.com
	[209.85.217.172]) (using TLSv1 with cipher RC4-SHA (128/128 bits))
	(No client certificate requested)
	by olra.theworths.org (Postfix) with ESMTPS id 69D4F431FBD
	for <notmuch@notmuchmail.org>; Tue, 14 Oct 2014 07:50:29 -0700 (PDT)
Received: by mail-lb0-f172.google.com with SMTP id b6so8385780lbj.17
	for <notmuch@notmuchmail.org>; Tue, 14 Oct 2014 07:50:27 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113;
	h=from:to:cc:subject:date:message-id:in-reply-to:references;
	bh=eAI7N8poDF3PIMrCDz3rVjDG+OyawBHlqYfQzzyavUA=;
	b=tm+ZyPx3Iuvub3iragIRJLOWwZ9bNMB9LdWaqdg71FAZx8IEH7wvQS4NyuTJtNiXO8
	3pzaOtePlbw/1zsq1YJYFwLJr1RMXwV/zDxdtilaSxkXkeON9xze579IgancDlvNO/9q
	jbHYy3jsroFQ4FVRMzTxh/9MgV67hBbAW96tRQokv4R5WHzwQg9/SzAf403D7Wvkfrlr
	Ew0OT9u5NoW2DphxjtpZ0Y4Z6GliDyrxt2wODkzmDxiz5tEWWEWjBX+62F4TQqEr4/5k
	yaz03V+z9pP5DhVmXDTOAvU81k2Y8dqA4MhwLAXj4T7vr7bVUthfUiL3y1Xd++vxb6yq
	6AMA==
X-Received: by 10.112.48.3 with SMTP id h3mr5825852lbn.71.1413298227589;
	Tue, 14 Oct 2014 07:50:27 -0700 (PDT)
Received: from localhost (shpd-178-69-250-75.vologda.ru. [178.69.250.75])
	by mx.google.com with ESMTPSA id w10sm806201lae.24.2014.10.14.07.50.26
	for <multiple recipients>
	(version=TLSv1.2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128);
	Tue, 14 Oct 2014 07:50:26 -0700 (PDT)
From: Sergei Shilovsky <sshilovsky@gmail.com>
To: notmuch@notmuchmail.org
Subject: [PATCH] man: add notes about issues with notmuch-count
Date: Tue, 14 Oct 2014 18:48:32 +0400
Message-Id: <1413298112-19912-2-git-send-email-sshilovsky@gmail.com>
X-Mailer: git-send-email 2.1.0
In-Reply-To: <1413298112-19912-1-git-send-email-sshilovsky@gmail.com>
References: <1413298112-19912-1-git-send-email-sshilovsky@gmail.com>
X-BeenThere: notmuch@notmuchmail.org
X-Mailman-Version: 2.1.13
Precedence: list
List-Id: "Use and development of the notmuch mail system."
	<notmuch.notmuchmail.org>
List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
	<mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
List-Archive: <http://notmuchmail.org/pipermail/notmuch>
List-Post: <mailto:notmuch@notmuchmail.org>
List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
	<mailto:notmuch-request@notmuchmail.org?subject=subscribe>
X-List-Received-Date: Tue, 14 Oct 2014 14:50:34 -0000

1. notmuch count --output=messages outputs estimated number

2. notmuch count --output=(files|threads) can be slow
---
 doc/man1/notmuch-count.rst | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/doc/man1/notmuch-count.rst b/doc/man1/notmuch-count.rst
index ca78c18..3bb6981 100644
--- a/doc/man1/notmuch-count.rst
+++ b/doc/man1/notmuch-count.rst
@@ -10,7 +10,7 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-Count messages matching the search terms.
+Count (an estimate of) the number of messages matching the search terms.
 
 The number of matching messages (or threads) is output to stdout.
 
@@ -25,16 +25,20 @@ Supported options for **count** include
     ``--output=(messages|threads|files)``
 
         **messages**
-            Output the number of matching messages. This is the default.
+            Output an estimate of the number of matching messages. This is the
+            default.
 
         **threads**
-            Output the number of matching threads.
+            Output the exact number of matching threads. The search is
+            performed, so this is a significantly heavier operation than
+            ``--output=messages``.
 
         **files**
-            Output the number of files associated with matching
+            Output the exact number of files associated with matching
             messages. This may be bigger than the number of matching
             messages due to duplicates (i.e. multiple files having the
-            same message-id).
+            same message-id). The search is performed, so this is a
+            significantly heavier operation than ``--output=messages``.
 
     ``--exclude=(true|false)``
         Specify whether to omit messages matching search.tag\_exclude
-- 
2.1.0