[PATCH RFC3.5 11/12] Docs: send-email: Clarification of sendemail.<identity>

[Michael Witten <mfwitten@gmail.com>]

Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
 Documentation/git-send-email.txt |   43 ++++++++++++++++++++++++++++++++++++++
 1 files changed, 43 insertions(+), 0 deletions(-)

diff --git a/Documentation/git-send-email.txt b/Documentation/git-send-email.txt
index 93c39e1..3b36ac7 100644
--- a/Documentation/git-send-email.txt
+++ b/Documentation/git-send-email.txt
@@ -194,6 +194,7 @@ Automating
 	'sendemail.<identity>' subsection to take precedence over
 	values in the 'sendemail' section. The default identity is
 	the value of the 'sendemail.identity' configuration variable.
+	See the *CONFIGURATION* section for more details.
 
 --[no-]signed-off-by-cc::
 	If this is set, add emails found in Signed-off-by: or Cc: lines to the
@@ -282,6 +283,48 @@ default to '--validate'.
 CONFIGURATION
 -------------
 
+Configuration subsections are very useful in combination with '--identity'.
+For instance, consider a configuration file that contains the following:
+
+	...
+
+	[sendemail]
+		smtpencryption = tls
+		smtpserver     = smtp.example.com
+		smtpuser       = user@example.com
+		suppresscc     = self
+		confirm        = always
+		identity       = test
+
+	[sendemail "test"]
+		to = user@example.com
+
+	[sendemail "git-rfc"]
+		to = git@vger.kernel.org
+
+	[sendemail "git-submit"]
+		to      = gitster@pobox.com
+		cc      = git@vger.kernel.org
+		confirm = never
+
+	...
+
+With this configuration, 'send-email' processes the variables in `[sendemail]`.
+Then, 'sendemail.identity' tells 'send-email' to process the variables in the
+`[sendemail "test"]` subsection. Thus:
+
+	git send-email <patch>
+
+would send `<patch>` to `user@example.com` as a "test". When the user
+decides that `<patch>` is ready to be sent for real, the user could
+email the 'git' mailing list to make a request for comments (RFC):
+
+	git send-email <patch> --identity git-rfc
+
+Then, for final submission:
+
+	git send-email <patch> --identity git-submit
+
 Composing
 ~~~~~~~~~
 
-- 
1.6.2.2.479.g2aec