~sircmpwn/git-send-email.io

ref: 0.1.4 git-send-email.io/index.html -rw-r--r-- 26.7 KiB
b824632eDrew DeVault Use reply["Cc"] for copying list 1 year, 7 months ago
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
<!doctype html>
<html>
  <head>
    <title>Learn to use email with git!</title>
    <link rel="stylesheet" type="text/css" href="index.css" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta charset="utf-8" />
  </head>
  <body>
    <div class="container">
      <h1>email + git = &lt;3</h1>
      <p>
        <a target="_blank" rel="noopener" href="https://git-scm.com">Git</a>
        ships with built-in tools for collaborating over email. With this
        guide, you'll be contributing to email-driven projects like the Linux
        kernel, PostgreSQL, or even git itself in no time.
      </p>
      <input type="radio" class="magic" name="progress" id="step-1" checked />
      <input type="radio" class="magic" name="progress" id="step-2" />
      <input type="radio" class="magic" name="progress" id="step-3" />
      <input type="radio" class="magic" name="progress" id="step-4" />
      <input type="radio" class="magic" name="progress" id="step-5" />
      <div class="step step-1" style="background-image: url('/static/task1.png')">
        <h2>
          <small>Step one</small> Installation
        </h2>
        <label class="prev" style="visibility: hidden"></label>
        <div class="content">
          <p class="hardwrap">
            Let's start by installing the appropriate packages for your
            operating system.
          </p>
          <div class="accordion">
            <input type="radio" class="magic" name="os" id="os-arch" checked />
            <input type="radio" class="magic" name="os" id="os-alpine" />
            <input type="radio" class="magic" name="os" id="os-centos" />
            <input type="radio" class="magic" name="os" id="os-debian" />
            <input type="radio" class="magic" name="os" id="os-fedora" />
            <input type="radio" class="magic" name="os" id="os-freebsd" />
            <input type="radio" class="magic" name="os" id="os-gentoo" />
            <input type="radio" class="magic" name="os" id="os-macos" />
            <input type="radio" class="magic" name="os" id="os-nixos" />
            <input type="radio" class="magic" name="os" id="os-opensuse" />
            <input type="radio" class="magic" name="os" id="os-pkgsrc" />
            <input type="radio" class="magic" name="os" id="os-ubuntu" />
            <input type="radio" class="magic" name="os" id="os-windows" />
            <div class="item os-arch">
              <label for="os-arch">
                <img src="/static/arch.png" />
                Arch Linux
              </label>
              <div class="content">
                <p>
                  The <code>git</code> package includes the git email tools,
                  though you might need to install a few additional packages to
                  get it fully working.
                  Run this to install it:
                </p>
                <pre>sudo pacman -Syu --needed git perl-authen-sasl perl-net-smtp-ssl perl-mime-tools</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-alpine">
              <label for="os-alpine">
                <img src="/static/alpine.png" />
                Alpine Linux
              </label>
              <div class="content">
                <p>
                  The <code>git-email</code> package includes the git email
                  tools. Run this to install it:
                </p>
                <pre>sudo apk add git git-email</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-centos">
              <label for="os-centos">
                <img src="/static/centos.png" />
                CentOS
              </label>
              <div class="content">
                <p>
                  The <code>git-email</code> package includes the git email
                  tools. Run this to install it:
                </p>
                <pre>sudo yum install git git-email</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-debian">
              <label for="os-debian">
                <img src="/static/debian.png" />
                Debian
              </label>
              <div class="content">
                <p>
                  The <code>git-email</code> package includes the git email
                  tools. Run this to install it:
                </p>
                <pre>sudo apt install git git-email</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-fedora">
              <label for="os-fedora">
                <img src="/static/fedora.png" />
                Fedora
              </label>
              <div class="content">
                <p>
                  The <code>git-email</code> package includes the git email
                  tools. Run this to install it:
                </p>
                <pre>sudo dnf install git git-email</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-freebsd">
              <label for="os-freebsd">
                <img src="/static/freebsd.png" />
                FreeBSD
              </label>
              <div class="content">
                <p>
                  The <code>git</code> package includes the git email tools.
                  Run this to install it:
                </p>
                <pre>pkg install git</pre>
                <p>
                  Or, to install from ports:
                </p>
                <pre>cd /usr/ports/devel/git &amp;&amp; make install clean</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-gentoo">
              <label for="os-gentoo">
                <img src="/static/gentoo.png" />
                Gentoo
              </label>
              <div class="content">
                <p>
                  The <code>git</code> package includes the git email tools.
                  Run this to install it:
                </p>
                <pre>emerge dev-vcs/git</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-macos">
              <label for="os-macos">
                <img src="/static/apple.png" />
                macOS
              </label>
              <div class="content">
                <p>
                  The official git bundle from
                    <a href="https://git-scm.com/download/mac">git-scm.com</a>
                  includes the git email tools.
                </p>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-nixos">
              <label for="os-nixos">
                <img src="/static/nixos.png" />
                Nixpkgs
              </label>
              <div class="content">
                <p>
                  The <code>gitAndTools.gitFull</code> package from the NixOS
                  channel includes the git email tools. Run this to install it:
                </p>
                <pre>nix-env -iA nixos.gitAndTools.gitFull</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-opensuse">
              <label for="os-opensuse">
                <img src="/static/suse.png" />
                openSUSE
              </label>
              <div class="content">
                <p>
                  The <code>git-email</code> package includes the git email
                  tools. Run this to install it:
                </p>
                <pre>sudo zypper install git-email</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-pkgsrc">
              <label for="os-pkgsrc">
                <img src="/static/pkgsrc.png" />
                pkgsrc
              </label>
              <div class="content">
                <p>
                  The <code>devel/git</code> package includes the git email
                  tools. Run this to install it:
                </p>
                <pre>sudo pkg_add git</pre>
                <p>
                  Or, to build from source:
                </p>
                <pre>cd /usr/pkgsrc/devel/git &amp;&amp; make install </pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-ubuntu">
              <label for="os-ubuntu">
                <img src="/static/ubuntu.png" />
                Ubuntu
              </label>
              <div class="content">
                <p>
                  The <code>git-email</code> package includes the git email
                  tools. Run this to install it:
                </p>
                <pre>sudo apt install git git-email</pre>
                <label for="step-2">Next</label>
              </div>
            </div>
            <div class="item os-windows">
              <label for="os-windows">
                <img src="/static/windows.png" />
                Microsoft Windows
              </label>
              <div class="content">
                <p>
                  The official git bundle from
                    <a href="https://git-scm.com/download/windows">git-scm.com</a>
                  includes the git email tools.
                </p>
                <label for="step-2">Next</label>
              </div>
            </div>
          </div>
          <div class="alert" style="margin-top: 1rem">
            Don't see your OS here? Consult your OS documentation for
            installation, and once you finish this tutorial, send a patch
            adding yours to our
            <a
              href="https://git.sr.ht/~sircmpwn/git-send-email.io"
              target="_blank"
            >git repository</a>.
          </div>
        </div>
        <label class="next" for="step-2"></label>
      </div>
      <div class="step step-2" style="background-image: url('/static/task2.png')">
        <h2>
          <small>Step two</small> Configuration
        </h2>
        <label class="prev" for="step-1"></label>
        <div class="content">
          <p class="hardwrap">
            You only need to complete this step once for each machine you
            intend to send emails from.
          </p>
          <div class="accordion">
            <input type="radio" class="magic" name="mailer" id="mailer-gmail" />
            <input type="radio" class="magic" name="mailer" id="mailer-protonmail" />
            <input type="radio" class="magic" name="mailer" id="mailer-sendmail" />
            <input type="radio" class="magic" name="mailer" id="mailer-generic" checked />
            <div class="item mailer-gmail">
              <label for="mailer-gmail">Gmail</label>
              <div class="content">
                <p>
                  Add these details to your <code>~/.git/config</code> file:
                </p>
                <pre>[sendemail]
	smtpserver = smtp.gmail.com
	smtpuser = you@gmail.com
	smtpencryption = tls
	smtpserverport = 587</pre>
                <p>
                  Be sure to fill in your own email address under
                  <code>smtpuser</code>. You also need to obtain an
                  application-specific password for git from the <a
                    href="https://security.google.com/settings/security/apppasswords"
                    target="_blank"
                  >app passwords</a> page on your Google account. To store this
                  password with git, run this command:
                </p>
                <pre>git config --global sendemail.password 'your password'</pre>
                <p>
                  Also, if you haven't yet, run these
                  commands - again, making the appropriate changes:
                </p>
                <pre>git config --global user.email "you@gmail.com"
<!--              -->git config --global user.name "Your Name"</pre>
                <label for="step-3">Next</label>
              </div>
            </div>
            <div class="item mailer-protonmail">
              <label for="mailer-protonmail">Protonmail</label>
              <div class="content">
                <p>
                  Protonmail does not support the open, industry-standard
                  protocols necessary for git send-email to work
                  out-of-the-box. You need to install &amp; configure
                  <a href="https://github.com/emersion/hydroxide">Hydroxide</a>
                  to connect to Protonmail with SMTP. Once you have configured
                  Hydroxide, use its SMTP details along with the generic
                  instructions below.
                </p>
                <label for="step-3">Next</label>
              </div>
            </div>
            <div class="item mailer-sendmail">
              <label for="mailer-sendmail">sendmail</label>
              <div class="content">
                <p>
                  If you already have sendmail configured to send email
                  locally, you don't have to configure anything at all!
                </p>
                <label for="step-3">Next</label>
              </div>
            </div>
            <div class="item mailer-generic">
              <label for="mailer-generic">Generic instructions</label>
              <div class="content">
                <p>
                  Your email provider should have instructions somewhere for
                  <strong>SMTP access</strong>. Look these details up, and then
                  add this to your <code>~/.git/config</code> file:
                </p>
                <pre>[sendemail]
	smtpserver = mail.example.org
	smtpuser = you@example.org
	smtpencryption = tls
	smtpserverport = 587</pre>
                <p>
                  Be sure to fill in the appropriate values for your email
                  provider - you will probably only have to fill in
                  <code>smtpserver</code> and <code>smtpuser</code>. Also, if
                  you haven't yet, run these commands - again, making the
                  appropriate changes:
                </p>
                <pre>git config --global user.email "you@example.org"
<!--              -->git config --global user.name "Your Name"</pre>
                <label for="step-3">Next</label>
              </div>
            </div>
          </div>
        </div>
        <label class="next" for="step-3"></label>
      </div>
      <div class="step step-3" style="background-image: url('/static/task3.png')">
        <h2>
          <small>Step three</small> Give it a shot!
        </h2>
        <label class="prev" for="step-2"></label>
        <div class="content">
          <p class="hardwrap">
            It's time to take it for a spin - we're going to send a patch.
            Ready?
          </p>
          <div class="content well">
            <ol>
              <li>
                <strong>Clone the upstream repository</strong>. No need to make a
                fork! We have prepared a repository for you to test with:
                <pre>git clone <a
                  href="https://git.sr.ht/~sircmpwn/email-test-drive"
                >https://git.sr.ht/~sircmpwn/email-test-drive</a>
<!--              -->cd email-test-drive</pre>
              </li>
              <li>
                <strong>Make your changes</strong>. Let's add a file with your
                progress so far:
                <pre>echo "I'm about to try git send-email!" &gt;your-name</pre>
                <div style="margin: 0.5rem 0">
                  Be sure to change <code>your-name</code> to your own!
                </div>
              </li>
              <li>
                <strong>Commit your changes</strong>. Check out the official
                (and free) <a
                  href="https://git-scm.com/book/en/v2"
                  target="_blank"
                  rel="noopener"
                >Pro Git</a> book if you don't know how to do this.
                <pre>git add your-name
<!--              -->git commit -m "Demonstrate that I can use git send-email!"</pre>
              </li>
              <li>
                <strong>Send the patch</strong>! If you check out the
                <code>README.md</code> file, you'll note that patches should be
                sent to <a href="mailto:~sircmpwn/email-test-drive@lists.sr.ht">
                  ~sircmpwn/email-test-drive@lists.sr.ht</a>.
                <pre>git send-email --to="~sircmpwn/email-test-drive@lists.sr.ht" HEAD^</pre>
                <div style="margin: 0.5rem 0">
                  When prompted for an <code>In-Reply-To</code>, you can ignore
                  it for now (just press enter). Follow the rest of the prompts
                  and you've done it! If you have any problems at this step,
                  feel free to
                  <a href="mailto:sir@cmpwn.com?subject=git-send-email%20help">
                    email us
                  </a> for help. If it worked, you should see your email appear
                  in the <a
                    target="_blank"
                    rel="noopener"
                    href="https://lists.sr.ht/~sircmpwn/email-test-drive"
                  >mailing list archives</a> momentarily!
                </div>
              </li>
              <li>
                <strong>Check your inbox</strong>... someone has some feedback
                on your patch!
              </li>
            </ol>
            <label for="step-4">Next</label>
          </div>
          <div class="alert" style="margin-top: 1rem">
            <strong>Warning!</strong> Some people think that they can get
            away with sending patches through some means other than <code>
            git send-email</code>, but you can't. Your patches will be broken
            and a nuisance to the maintainers whose inbox they land in.
            Follow the golden rule: <em>just use git send-email</em>.
          </div>
        </div>
        <label class="next" for="step-4"></label>
      </div>
      <div class="step step-4" style="background-image: url('/static/task4.png')">
        <h2>
          <small>Step four</small> Dealing with feedback
        </h2>
        <label class="prev" for="step-3"></label>
				<div class="content">
					<div class="content well">
            <p style="margin-bottom: 0.5rem">
              No one ever gets it right on the first try. Don't worry, it's all
              part of the process! You may receive some feedback on your patch
              from the maintainers of the software. This feedback will arrive in
              the form of a reply to your email. If you have any questions,
              just reply back - and remember to "reply all"! In the meantime,
              let's fix the patch.
            </p>
            <div class="alert">
              In this tutorial, the feedback was generated by a bot, but feel
              free to reply to get the hang of it. You need to make sure your
              email client is configured to write emails in <strong>plain
              text</strong> before you do, and please try to avoid
              <a href="/top-posting.html" target="_blank">top posting</a>.
              We also have an
              <a
                target="_blank"
                href="https://man.sr.ht/lists.sr.ht/etiquette.md"
              >etiquette guide</a> that'll help you avoid any faux pas.
            </div>
            <ol>
              <li>
                <strong>Make the changes</strong>. Update the files to match the
                changes requested by the maintainers. We'll leave this to you.
              </li>
              <li>
                <strong>Amend your commit</strong>. Git is designed for you to
                <em>edit</em> your commit history. It's not set in stone! The
                maintainers reviewing your work don't want to merge a patch
                which has mistakes, even if it's followed up by a fix, so
                you'll have to <strong>amend</strong> your previous commit:
                <pre>git commit -a --amend</pre>
                <p>
                  First time amending a commit? Amending and rebasing commits
                  is an essential skill in this workflow. Stay tuned for our
                  comprehensive guide to rebasing - subscribe to
                  <a
                    href="https://lists.sr.ht/~sircmpwn/sr.ht-announce"
                    target="_blank"
                  >sr.ht-announce</a> to get notified when it's ready.
                </p>
              </li>
              <li>
                <strong>Set the default "to" address</strong>. Let's make this
                easier on ourselves by setting the default email address for
                this repo, so we needn't enter it every time:
                <pre>git config sendemail.to "~sircmpwn/email-test-drive@lists.sr.ht"</pre>
              </li>
              <li>
                <strong>Find the message ID to reply to</strong>. Don't stress
                too much about getting this step right, but it's a nice
                courtesy for the people receiving your patch. On the
                <a href="https://lists.sr.ht/~sircmpwn/email-test-drive">
                  mailing list archives</a>,
                look up the latest email in your thread and expand "Details" to
                find the <code>Message ID</code>. Copy this for the next step.
              </li>
              <li>
                <strong>Send the new patch</strong>! This time we'll use
                <code>-v2</code> to indicate that this the second version of
                this patch, and we'll use <code>--in-reply-to</code> with the
                message ID we found in the last step. If we do this again,
                we'll use <code>-v3</code> and a new message ID.
                <pre>git send-email --annotate -v2 \
<!--              -->  --in-reply-to="&lt;message-id&gt;" HEAD^</pre>
                <p>
                  Note that we also specified the "--annotate" flag. This is
                  going to open the email in our editor before sending it out,
                  so we can make any changes. We're going to add some "timely
                  commentary". Look for the "---" and add a short summary of
                  the differences since the first patch on the next line. It
                  should look something like this:
                </p>
                <pre>Subject: [PATCH v2] Demonstrate that I can use git send-email!

<!--              -->---
<!--              -->This fixes the issues raised from the first patch.

<!--              -->src/main.c | 4 +---
<!--              -->1 file changed, 1 insertion(+), 3 deletions(-)</pre>
								<p>
                  This text gives the maintainers some extra context about your
                  patch, but doesn't make it into the final git log. Close your
                  editor, follow the prompts again, and that's it - you're done!
									Congratulations!
                </p>
                <p>
                  If you want some more tips on using git send-email, check out
                  the next page.
								</p>
              </li>
            </ol>
						<label for="step-5">Next</label>
					</div>
        </div>
        <label class="next" for="step-5"></label>
      </div>
      <div class="step step-5" style="background-image: url('/static/task5.png')">
        <!-- TODO: Move step 5 onto a separate page so each tip is linkable? -->
        <h2>
          Tips &amp; tricks
        </h2>
        <label class="prev" for="step-4"></label>
        <div class="content wells">
          <p class="hardwrap">
            Miscellaneous tips and tricks which may serve you well as you use
            git send-email.
          </p>
          <div class="well">
            <h3>Sending several patches at once</h3>
            <p>Use this to send the last 3 commits:</p>
            <pre>git send-email HEAD~3</pre>
            <p>Or all commits since a particular one:</p>
            <pre>git send-email 209210d30780ec64995594b77fde3d718b655542</pre>
            <p>Or just the second-to-last commit:</p>
            <pre>git send-email -1 HEAD^^</pre>
            <p>
              See <a
                href="https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection"
                target="_blank"
              >Revision Selection</a> for more.
            </p>
          </div>
          <div class="well">
            <h3>Specifying a sub-project</h3>
            <p>
              Some projects use a single mailing list for several git
              repositories. Try this to clarify that you're working on the
              "foobar" project:
            </p>
            <pre>git config format.subjectPrefix "PATCH foobar"</pre>
          </div>
          <div class="well">
            <h3>Using --annotate every time</h3>
            <pre>git config --global sendemail.annotate yes</pre>
          </div>
          <div class="well">
            <h3>"Signing off" on your commits</h3>
            <p>
              Some projects, such as the Linux kernel, will ask you to "sign
              off" on your commits. To do this, add <code>--signoff</code> (or
              <code>-s</code>) to <code>git send-email</code>. To set it as the
              default for that git repository:
            </p>
            <pre>git config format.signOff yes</pre>
            <p>
              By doing this you acknowledge that you have read the
              <a
                href="https://developercertificate.org/"
                target="_blank"
                rel="noopener"
              >Developer Certificate of Origin (DCO)</a>.
            </p>
          </div>
          <div class="well">
            <h3>More approaches to authentication</h3>
            <p>
              This tutorial configures git in a way that causes send-email to
              prompt for your password, which you may find annoying. There are
              other ways to authenticate - the simplest of which is:
            </p>
            <pre>git config --global sendemail.smtpPass 'your password'</pre>
            <p>
              For more sophisticated solutions, such as integration with your
              keyring, see the <a
                href="https://git-scm.com/docs/gitcredentials"
              >git-credential</a> man page.
            </p>
          </div>
          <label class="next" for="step-1">Back to the start</label>
        </div>
        <label class="next" style="visibility: hidden"></label>
      </div>
      <footer>
        This tutorial brought to you courtesy of
        <a href="https://sourcehut.org">sourcehut</a>, the hacker's forge. 100%
        open source Git &amp; Mercurial hosting, continuous integration,
        mailing lists, and <strong>no JavaScript</strong>!
        <a href="https://meta.sr.ht/register">Try it today</a>!
      </footer>
    </div>
  </body>
</html>