Autogenerated HTML docs for v2.50.0-173-g8b6f1

Author: gitster

RelNotes/2.51.0.adoc

@@ -31,6 +31,11 @@ UI, Workflows & Features
    use the compact-summary format, intead of diffstat, when showing
    the summary of the incoming changes.
 
+ * "git imap-send" has been broken for a long time, which has been
+   resurrected and then taught to talk OAuth2.0 etc.
+
+ * Some error messages from "git imap-send" has been updated.
+
 
 Performance, Internal Implementation, Development Support etc.
 --------------------------------------------------------------
@@ -51,6 +56,8 @@ Performance, Internal Implementation, Development Support etc.
  * A test helper "test_seq" function learned the "-f <fmt>" option,
    which allowed us to simplify a lot of test scripts.
 
+ * A lot of stale stuff has been removed from the contrib/ hierarchy.
+
 
 Fixes since v2.50
 -----------------

git-config.html

@@ -6296,8 +6296,10 @@ <h3 id="_variables">Variables</h3>
 <dt class="hdlist1">imap.folder</dt>
 <dd>
 <p>The folder to drop the mails into, which is typically the Drafts
-folder. For example: "INBOX.Drafts", "INBOX/Drafts" or
-"[Gmail]/Drafts". Required.</p>
+folder. For example: <code>INBOX.Drafts</code>, <code>INBOX/Drafts</code> or
+[<code>Gmail</code>]<code>/Drafts</code>. The IMAP folder to interact with MUST be specified;
+the value of this configuration variable is used as the fallback
+default value when the <code>--folder</code> option is not given.</p>
 </dd>
 <dt class="hdlist1">imap.tunnel</dt>
 <dd>
@@ -6344,8 +6346,9 @@ <h3 id="_variables">Variables</h3>
 <p>Specify the authentication method for authenticating with the IMAP server.
 If Git was built with the NO_CURL option, or if your curl version is older
 than 7.34.0, or if you&#8217;re running git-imap-send with the <code>--no-curl</code>
-option, the only supported method is <em>CRAM-MD5</em>. If this is not set
-then <em>git imap-send</em> uses the basic IMAP plaintext LOGIN command.</p>
+option, the only supported methods are <code>PLAIN</code>, <code>CRAM-MD5</code>, <code>OAUTHBEARER</code>
+and <code>XOAUTH2</code>. If this is not set then <code>git</code> <code>imap-send</code> uses the basic IMAP
+plaintext <code>LOGIN</code> command.</p>
 </dd>
 <dt class="hdlist1">include.path</dt>
 <dt class="hdlist1">includeIf.&lt;condition&gt;.path</dt>

git-imap-send.adoc

@@ -9,21 +9,24 @@ git-imap-send - Send a collection of patches from stdin to an IMAP folder
 SYNOPSIS
 --------
 [verse]
-'git imap-send' [-v] [-q] [--[no-]curl]
+'git imap-send' [-v] [-q] [--[no-]curl] [(--folder|-f) <folder>]
+'git imap-send' --list
 
 
 DESCRIPTION
 -----------
-This command uploads a mailbox generated with 'git format-patch'
+This command uploads a mailbox generated with `git format-patch`
 into an IMAP drafts folder.  This allows patches to be sent as
 other email is when using mail clients that cannot read mailbox
 files directly. The command also works with any general mailbox
-in which emails have the fields "From", "Date", and "Subject" in
+in which emails have the fields `From`, `Date`, and `Subject` in
 that order.
 
 Typical usage is something like:
 
-git format-patch --signoff --stdout --attach origin | git imap-send
+------
+$ git format-patch --signoff --stdout --attach origin | git imap-send
+------
 
 
 OPTIONS
@@ -37,6 +40,11 @@ OPTIONS
 --quiet::
 	Be quiet.
 
+-f <folder>::
+--folder=<folder>::
+	Specify the folder in which the emails have to saved.
+	For example: `--folder=[Gmail]/Drafts` or `-f INBOX/Drafts`.
+
 --curl::
 	Use libcurl to communicate with the IMAP server, unless tunneling
 	into it.  Ignored if Git was built without the USE_CURL_FOR_IMAP_SEND
@@ -47,6 +55,8 @@ OPTIONS
 	using libcurl.  Ignored if Git was built with the NO_OPENSSL option
 	set.
 
+--list::
+	Run the IMAP LIST command to output a list of all the folders present.
 
 CONFIGURATION
 -------------
@@ -102,20 +112,56 @@ Using Gmail's IMAP interface:
 
 ---------
 [imap]
-	folder = "[Gmail]/Drafts"
-	host = imaps://imap.gmail.com
-	user = [email protected]
-	port = 993
+    folder = "[Gmail]/Drafts"
+    host = imaps://imap.gmail.com
+    user = [email protected]
+    port = 993
 ---------
 
+Gmail does not allow using your regular password for `git imap-send`.
+If you have multi-factor authentication set up on your Gmail account, you
+can generate an app-specific password for use with `git imap-send`.
+Visit https://security.google.com/settings/security/apppasswords to create
+it. Alternatively, use OAuth2.0 authentication as described below.
+
 [NOTE]
 You might need to instead use: `folder = "[Google Mail]/Drafts"` if you get an error
-that the "Folder doesn't exist".
+that the "Folder doesn't exist". You can also run `git imap-send --list` to get a
+list of available folders.
 
 [NOTE]
 If your Gmail account is set to another language than English, the name of the "Drafts"
 folder will be localized.
 
+If you want to use OAuth2.0 based authentication, you can specify
+`OAUTHBEARER` or `XOAUTH2` mechanism in your config. It is more secure
+than using app-specific passwords, and also does not enforce the need of
+having multi-factor authentication. You will have to use an OAuth2.0
+access token in place of your password when using this authentication.
+
+---------
+[imap]
+    folder = "[Gmail]/Drafts"
+    host = imaps://imap.gmail.com
+    user = [email protected]
+    port = 993
+    authmethod = OAUTHBEARER
+---------
+
+Using Outlook's IMAP interface:
+
+Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it
+supports only `XOAUTH2` as the mechanism.
+
+---------
+[imap]
+    folder = "Drafts"
+    host = imaps://outlook.office365.com
+    user = [email protected]
+    port = 993
+    authmethod = XOAUTH2
+---------
+
 Once the commits are ready to be sent, run the following command:
 
   $ git format-patch --cover-letter -M --stdout origin/master | git imap-send
@@ -124,6 +170,10 @@ Just make sure to disable line wrapping in the email client (Gmail's web
 interface will wrap lines no matter what, so you need to use a real
 IMAP client).
 
+In case you are using OAuth2.0 authentication, it is easier to use credential
+helpers to generate tokens. Credential helpers suggested in
+linkgit:git-send-email[1] can be used for `git imap-send` as well.
+
 CAUTION
 -------
 It is still your responsibility to make sure that the email message

git-imap-send.html

@@ -452,26 +452,29 @@ <h2 id="_name">NAME</h2>
 <h2 id="_synopsis">SYNOPSIS</h2>
 <div class="sectionbody">
 <div class="verseblock">
-<pre class="content"><em>git imap-send</em> [-v] [-q] [--[no-]curl]</pre>
+<pre class="content"><em>git imap-send</em> [-v] [-q] [--[no-]curl] [(--folder|-f) &lt;folder&gt;]
+<em>git imap-send</em> --list</pre>
 </div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_description">DESCRIPTION</h2>
 <div class="sectionbody">
 <div class="paragraph">
-<p>This command uploads a mailbox generated with <em>git format-patch</em>
+<p>This command uploads a mailbox generated with <code>git</code> <code>format-patch</code>
 into an IMAP drafts folder.  This allows patches to be sent as
 other email is when using mail clients that cannot read mailbox
 files directly. The command also works with any general mailbox
-in which emails have the fields "From", "Date", and "Subject" in
+in which emails have the fields <code>From</code>, <code>Date</code>, and <code>Subject</code> in
 that order.</p>
 </div>
 <div class="paragraph">
 <p>Typical usage is something like:</p>
 </div>
-<div class="paragraph">
-<p>git format-patch --signoff --stdout --attach origin | git imap-send</p>
+<div class="listingblock">
+<div class="content">
+<pre>$ git format-patch --signoff --stdout --attach origin | git imap-send</pre>
+</div>
 </div>
 </div>
 </div>
@@ -490,6 +493,12 @@ <h2 id="_options">OPTIONS</h2>
 <dd>
 <p>Be quiet.</p>
 </dd>
+<dt class="hdlist1">-f &lt;folder&gt;</dt>
+<dt class="hdlist1">--folder=&lt;folder&gt;</dt>
+<dd>
+<p>Specify the folder in which the emails have to saved.
+For example: <code>--folder=</code>[<code>Gmail</code>]<code>/Drafts</code> or <code>-f</code> <code>INBOX/Drafts</code>.</p>
+</dd>
 <dt class="hdlist1">--curl</dt>
 <dd>
 <p>Use libcurl to communicate with the IMAP server, unless tunneling
@@ -502,6 +511,10 @@ <h2 id="_options">OPTIONS</h2>
 using libcurl.  Ignored if Git was built with the NO_OPENSSL option
 set.</p>
 </dd>
+<dt class="hdlist1">--list</dt>
+<dd>
+<p>Run the IMAP LIST command to output a list of all the folders present.</p>
+</dd>
 </dl>
 </div>
 </div>
@@ -523,8 +536,10 @@ <h2 id="_configuration">CONFIGURATION</h2>
 <dt class="hdlist1">imap.folder</dt>
 <dd>
 <p>The folder to drop the mails into, which is typically the Drafts
-folder. For example: "INBOX.Drafts", "INBOX/Drafts" or
-"[Gmail]/Drafts". Required.</p>
+folder. For example: <code>INBOX.Drafts</code>, <code>INBOX/Drafts</code> or
+[<code>Gmail</code>]<code>/Drafts</code>. The IMAP folder to interact with MUST be specified;
+the value of this configuration variable is used as the fallback
+default value when the <code>--folder</code> option is not given.</p>
 </dd>
 <dt class="hdlist1">imap.tunnel</dt>
 <dd>
@@ -571,8 +586,9 @@ <h2 id="_configuration">CONFIGURATION</h2>
 <p>Specify the authentication method for authenticating with the IMAP server.
 If Git was built with the NO_CURL option, or if your curl version is older
 than 7.34.0, or if you&#8217;re running git-imap-send with the <code>--no-curl</code>
-option, the only supported method is <em>CRAM-MD5</em>. If this is not set
-then <em>git imap-send</em> uses the basic IMAP plaintext LOGIN command.</p>
+option, the only supported methods are <code>PLAIN</code>, <code>CRAM-MD5</code>, <code>OAUTHBEARER</code>
+and <code>XOAUTH2</code>. If this is not set then <code>git</code> <code>imap-send</code> uses the basic IMAP
+plaintext <code>LOGIN</code> command.</p>
 </dd>
 </dl>
 </div>
@@ -639,11 +655,18 @@ <h2 id="_examples">EXAMPLES</h2>
 <div class="listingblock">
 <div class="content">
 <pre>[imap]
-        folder = "[Gmail]/Drafts"
-        host = imaps://imap.gmail.com
-        user = [email protected]
-        port = 993</pre>
+    folder = "[Gmail]/Drafts"
+    host = imaps://imap.gmail.com
+    user = [email protected]
+    port = 993</pre>
+</div>
 </div>
+<div class="paragraph">
+<p>Gmail does not allow using your regular password for <code>git</code> <code>imap-send</code>.
+If you have multi-factor authentication set up on your Gmail account, you
+can generate an app-specific password for use with <code>git</code> <code>imap-send</code>.
+Visit <a href="https://security.google.com/settings/security/apppasswords" class="bare">https://security.google.com/settings/security/apppasswords</a> to create
+it. Alternatively, use OAuth2.0 authentication as described below.</p>
 </div>
 <div class="admonitionblock note">
 <table>
@@ -653,7 +676,8 @@ <h2 id="_examples">EXAMPLES</h2>
 </td>
 <td class="content">
 You might need to instead use: <code>folder</code> <code>=</code> "[<code>Google</code> <code>Mail</code>]<code>/Drafts</code>" if you get an error
-that the "Folder doesn&#8217;t exist".
+that the "Folder doesn&#8217;t exist". You can also run <code>git</code> <code>imap-send</code> <code>--list</code> to get a
+list of available folders.
 </td>
 </tr>
 </table>
@@ -672,6 +696,40 @@ <h2 id="_examples">EXAMPLES</h2>
 </table>
 </div>
 <div class="paragraph">
+<p>If you want to use OAuth2.0 based authentication, you can specify
+<code>OAUTHBEARER</code> or <code>XOAUTH2</code> mechanism in your config. It is more secure
+than using app-specific passwords, and also does not enforce the need of
+having multi-factor authentication. You will have to use an OAuth2.0
+access token in place of your password when using this authentication.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>[imap]
+    folder = "[Gmail]/Drafts"
+    host = imaps://imap.gmail.com
+    user = [email protected]
+    port = 993
+    authmethod = OAUTHBEARER</pre>
+</div>
+</div>
+<div class="paragraph">
+<p>Using Outlook&#8217;s IMAP interface:</p>
+</div>
+<div class="paragraph">
+<p>Unlike Gmail, Outlook only supports OAuth2.0 based authentication. Also, it
+supports only <code>XOAUTH2</code> as the mechanism.</p>
+</div>
+<div class="listingblock">
+<div class="content">
+<pre>[imap]
+    folder = "Drafts"
+    host = imaps://outlook.office365.com
+    user = [email protected]
+    port = 993
+    authmethod = XOAUTH2</pre>
+</div>
+</div>
+<div class="paragraph">
 <p>Once the commits are ready to be sent, run the following command:</p>
 </div>
 <div class="literalblock">
@@ -684,6 +742,11 @@ <h2 id="_examples">EXAMPLES</h2>
 interface will wrap lines no matter what, so you need to use a real
 IMAP client).</p>
 </div>
+<div class="paragraph">
+<p>In case you are using OAuth2.0 authentication, it is easier to use credential
+helpers to generate tokens. Credential helpers suggested in
+<a href="git-send-email.html">git-send-email(1)</a> can be used for <code>git</code> <code>imap-send</code> as well.</p>
+</div>
 </div>
 </div>
 <div class="sect1">
@@ -723,7 +786,7 @@ <h2 id="_git">GIT</h2>
 </div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2025-02-14 21:38:14 -0800
+Last updated 2025-07-02 13:17:18 -0700
 </div>
 </div>
 </body>