1My First Contribution to the Git Project 2======================================== 3:sectanchors: 4 5[[summary]] 6== Summary 7 8This is a tutorial demonstrating the end-to-end workflow of creating a change to 9the Git tree, sending it for review, and making changes based on comments. 10 11[[prerequisites]] 12=== Prerequisites 13 14This tutorial assumes you're already fairly familiar with using Git to manage 15source code. The Git workflow steps will largely remain unexplained. 16 17[[related-reading]] 18=== Related Reading 19 20This tutorial aims to summarize the following documents, but the reader may find 21useful additional context: 22 23- `Documentation/SubmittingPatches` 24- `Documentation/howto/new-command.txt` 25 26[[getting-started]] 27== Getting Started 28 29[[cloning]] 30=== Clone the Git Repository 31 32Git is mirrored in a number of locations. Clone the repository from one of them; 33https://git-scm.com/downloads suggests one of the best places to clone from is 34the mirror on GitHub. 35 36---- 37$ git clone https://github.com/git/git git 38---- 39 40[[identify-problem]] 41=== Identify Problem to Solve 42 43//// 44Use + to indicate fixed-width here; couldn't get ` to work nicely with the 45quotes around "Pony Saying 'Um, Hello'". 46//// 47In this tutorial, we will add a new command, +git psuh+, short for ``Pony Saying 48`Um, Hello''' - a feature which has gone unimplemented despite a high frequency 49of invocation during users' typical daily workflow. 50 51(We've seen some other effort in this space with the implementation of popular 52commands such as `sl`.) 53 54[[setup-workspace]] 55=== Set Up Your Workspace 56 57Let's start by making a development branch to work on our changes. Per 58`Documentation/SubmittingPatches`, since a brand new command is a new feature, 59it's fine to base your work on `master`. However, in the future for bugfixes, 60etc., you should check that document and base it on the appropriate branch. 61 62For the purposes of this document, we will base all our work on the `master` 63branch of the upstream project. Create the `psuh` branch you will use for 64development like so: 65 66---- 67$ git checkout -b psuh origin/master 68---- 69 70We'll make a number of commits here in order to demonstrate how to send a topic 71with multiple patches up for review simultaneously. 72 73[[code-it-up]] 74== Code It Up! 75 76NOTE: A reference implementation can be found at 77https://github.com/nasamuffin/git/tree/psuh. 78 79[[add-new-command]] 80=== Adding a New Command 81 82Lots of the subcommands are written as builtins, which means they are 83implemented in C and compiled into the main `git` executable. Implementing the 84very simple `psuh` command as a built-in will demonstrate the structure of the 85codebase, the internal API, and the process of working together as a contributor 86with the reviewers and maintainer to integrate this change into the system. 87 88Built-in subcommands are typically implemented in a function named "cmd_" 89followed by the name of the subcommand, in a source file named after the 90subcommand and contained within `builtin/`. So it makes sense to implement your 91command in `builtin/psuh.c`. Create that file, and within it, write the entry 92point for your command in a function matching the style and signature: 93 94---- 95int cmd_psuh(int argc, const char **argv, const char *prefix) 96---- 97 98We'll also need to add the declaration of psuh; open up `builtin.h`, find the 99declaration for `cmd_push`, and add a new line for `psuh` immediately before it, 100in order to keep the declarations sorted: 101 102---- 103int cmd_psuh(int argc, const char **argv, const char *prefix); 104---- 105 106Be sure to `#include "builtin.h"` in your `psuh.c`. 107 108Go ahead and add some throwaway printf to that function. This is a decent 109starting point as we can now add build rules and register the command. 110 111NOTE: Your throwaway text, as well as much of the text you will be adding over 112the course of this tutorial, is user-facing. That means it needs to be 113localizable. Take a look at `po/README` under "Marking strings for translation". 114Throughout the tutorial, we will mark strings for translation as necessary; you 115should also do so when writing your user-facing commands in the future. 116 117---- 118int cmd_psuh(int argc, const char **argv, const char *prefix) 119{ 120 printf(_("Pony saying hello goes here.\n")); 121 return 0; 122} 123---- 124 125Let's try to build it. Open `Makefile`, find where `builtin/push.o` is added 126to `BUILTIN_OBJS`, and add `builtin/psuh.o` in the same way next to it in 127alphabetical order. Once you've done so, move to the top-level directory and 128build simply with `make`. Also add the `DEVELOPER=1` variable to turn on 129some additional warnings: 130 131---- 132$ echo DEVELOPER=1 >config.mak 133$ make 134---- 135 136NOTE: When you are developing the Git project, it's preferred that you use the 137`DEVELOPER` flag; if there's some reason it doesn't work for you, you can turn 138it off, but it's a good idea to mention the problem to the mailing list. 139 140NOTE: The Git build is parallelizable. `-j#` is not included above but you can 141use it as you prefer, here and elsewhere. 142 143Great, now your new command builds happily on its own. But nobody invokes it. 144Let's change that. 145 146The list of commands lives in `git.c`. We can register a new command by adding 147a `cmd_struct` to the `commands[]` array. `struct cmd_struct` takes a string 148with the command name, a function pointer to the command implementation, and a 149setup option flag. For now, let's keep mimicking `push`. Find the line where 150`cmd_push` is registered, copy it, and modify it for `cmd_psuh`, placing the new 151line in alphabetical order. 152 153The options are documented in `builtin.h` under "Adding a new built-in." Since 154we hope to print some data about the user's current workspace context later, 155we need a Git directory, so choose `RUN_SETUP` as your only option. 156 157Go ahead and build again. You should see a clean build, so let's kick the tires 158and see if it works. There's a binary you can use to test with in the 159`bin-wrappers` directory. 160 161---- 162$ ./bin-wrappers/git psuh 163---- 164 165Check it out! You've got a command! Nice work! Let's commit this. 166 167---- 168$ git add Makefile builtin.h builtin/psuh.c git.c 169$ git commit -s 170---- 171 172You will be presented with your editor in order to write a commit message. Start 173the commit with a 50-column or less subject line, including the name of the 174component you're working on, followed by a blank line (always required) and then 175the body of your commit message, which should provide the bulk of the context. 176Remember to be explicit and provide the "Why" of your change, especially if it 177couldn't easily be understood from your diff. When editing your commit message, 178don't remove the Signed-off-by line which was added by `-s` above. 179 180---- 181psuh: add a built-in by popular demand 182 183Internal metrics indicate this is a command many users expect to be 184present. So here's an implementation to help drive customer 185satisfaction and engagement: a pony which doubtfully greets the user, 186or, a Pony Saying "Um, Hello" (PSUH). 187 188This commit message is intentionally formatted to 72 columns per line, 189starts with a single line as "commit message subject" that is written as 190if to command the codebase to do something (add this, teach a command 191that). The body of the message is designed to add information about the 192commit that is not readily deduced from reading the associated diff, 193such as answering the question "why?". 194 195Signed-off-by: A U Thor <author@example.com> 196---- 197 198Go ahead and inspect your new commit with `git show`. "psuh:" indicates you 199have modified mainly the `psuh` command. The subject line gives readers an idea 200of what you've changed. The sign-off line (`-s`) indicates that you agree to 201the Developer's Certificate of Origin 1.1 (see the 202`Documentation/SubmittingPatches` +++[[dco]]+++ header). 203 204For the remainder of the tutorial, the subject line only will be listed for the 205sake of brevity. However, fully-fleshed example commit messages are available 206on the reference implementation linked at the top of this document. 207 208[[implementation]] 209=== Implementation 210 211It's probably useful to do at least something besides printing out a string. 212Let's start by having a look at everything we get. 213 214Modify your `cmd_psuh` implementation to dump the args you're passed: 215 216---- 217 int i; 218 219 ... 220 221 printf(Q_("Your args (there is %d):\n", 222 "Your args (there are %d):\n", 223 argc), 224 argc); 225 for (i = 0; i < argc; i++) 226 printf("%d: %s\n", i, argv[i]); 227 228 printf(_("Your current working directory:\n<top-level>%s%s\n"), 229 prefix ? "/" : "", prefix ? prefix : ""); 230 231---- 232 233Build and try it. As you may expect, there's pretty much just whatever we give 234on the command line, including the name of our command. (If `prefix` is empty 235for you, try `cd Documentation/ && ../bin-wrappers/git psuh`). That's not so 236helpful. So what other context can we get? 237 238Add a line to `#include "config.h"`. Then, add the following bits to the 239function body: 240 241---- 242 const char *cfg_name; 243 244... 245 246 git_config(git_default_config, NULL) 247 if (git_config_get_string_const("user.name", &cfg_name) > 0) 248 printf(_("No name is found in config\n")); 249 else 250 printf(_("Your name: %s\n"), cfg_name); 251---- 252 253`git_config()` will grab the configuration from config files known to Git and 254apply standard precedence rules. `git_config_get_string_const()` will look up 255a specific key ("user.name") and give you the value. There are a number of 256single-key lookup functions like this one; you can see them all (and more info 257about how to use `git_config()`) in `Documentation/technical/api-config.txt`. 258 259You should see that the name printed matches the one you see when you run: 260 261---- 262$ git config --get user.name 263---- 264 265Great! Now we know how to check for values in the Git config. Let's commit this 266too, so we don't lose our progress. 267 268---- 269$ git add builtin/psuh.c 270$ git commit -sm "psuh: show parameters & config opts" 271---- 272 273NOTE: Again, the above is for sake of brevity in this tutorial. In a real change 274you should not use `-m` but instead use the editor to write a meaningful 275message. 276 277Still, it'd be nice to know what the user's working context is like. Let's see 278if we can print the name of the user's current branch. We can mimic the 279`git status` implementation; the printer is located in `wt-status.c` and we can 280see that the branch is held in a `struct wt_status`. 281 282`wt_status_print()` gets invoked by `cmd_status()` in `builtin/commit.c`. 283Looking at that implementation we see the status config being populated like so: 284 285---- 286status_init_config(&s, git_status_config); 287---- 288 289But as we drill down, we can find that `status_init_config()` wraps a call 290to `git_config()`. Let's modify the code we wrote in the previous commit. 291 292Be sure to include the header to allow you to use `struct wt_status`: 293---- 294#include "wt-status.h" 295---- 296 297Then modify your `cmd_psuh` implementation to declare your `struct wt_status`, 298prepare it, and print its contents: 299 300---- 301 struct wt_status status; 302 303... 304 305 wt_status_prepare(the_repository, &status); 306 git_config(git_default_config, &status); 307 308... 309 310 printf(_("Your current branch: %s\n"), status.branch); 311---- 312 313Run it again. Check it out - here's the (verbose) name of your current branch! 314 315Let's commit this as well. 316 317---- 318$ git commit -sm "psuh: print the current branch" 319---- 320 321Now let's see if we can get some info about a specific commit. 322 323Luckily, there are some helpers for us here. `commit.h` has a function called 324`lookup_commit_reference_by_name` to which we can simply provide a hardcoded 325string; `pretty.h` has an extremely handy `pp_commit_easy()` call which doesn't 326require a full format object to be passed. 327 328Add the following includes: 329 330---- 331#include "commit.h" 332#include "pretty.h" 333---- 334 335Then, add the following lines within your implementation of `cmd_psuh()` near 336the declarations and the logic, respectively. 337 338---- 339 struct commit *c = NULL; 340 struct strbuf commitline = STRBUF_INIT; 341 342... 343 344 c = lookup_commit_reference_by_name("origin/master"); 345 346 if (c != NULL) { 347 pp_commit_easy(CMIT_FMT_ONELINE, c, &commitline); 348 printf(_("Current commit: %s\n"), commitline.buf); 349 } 350---- 351 352The `struct strbuf` provides some safety belts to your basic `char*`, one of 353which is a length member to prevent buffer overruns. It needs to be initialized 354nicely with `STRBUF_INIT`. Keep it in mind when you need to pass around `char*`. 355 356`lookup_commit_reference_by_name` resolves the name you pass it, so you can play 357with the value there and see what kind of things you can come up with. 358 359`pp_commit_easy` is a convenience wrapper in `pretty.h` that takes a single 360format enum shorthand, rather than an entire format struct. It then 361pretty-prints the commit according to that shorthand. These are similar to the 362formats available with `--pretty=FOO` in many Git commands. 363 364Build it and run, and if you're using the same name in the example, you should 365see the subject line of the most recent commit in `origin/master` that you know 366about. Neat! Let's commit that as well. 367 368---- 369$ git commit -sm "psuh: display the top of origin/master" 370---- 371 372[[add-documentation]] 373=== Adding Documentation 374 375Awesome! You've got a fantastic new command that you're ready to share with the 376community. But hang on just a minute - this isn't very user-friendly. Run the 377following: 378 379---- 380$ ./bin-wrappers/git help psuh 381---- 382 383Your new command is undocumented! Let's fix that. 384 385Take a look at `Documentation/git-*.txt`. These are the manpages for the 386subcommands that Git knows about. You can open these up and take a look to get 387acquainted with the format, but then go ahead and make a new file 388`Documentation/git-psuh.txt`. Like with most of the documentation in the Git 389project, help pages are written with AsciiDoc (see CodingGuidelines, "Writing 390Documentation" section). Use the following template to fill out your own 391manpage: 392 393// Surprisingly difficult to embed AsciiDoc source within AsciiDoc. 394[listing] 395.... 396git-psuh(1) 397=========== 398 399NAME 400---- 401git-psuh - Delight users' typo with a shy horse 402 403 404SYNOPSIS 405-------- 406[verse] 407'git-psuh' 408 409DESCRIPTION 410----------- 411... 412 413OPTIONS[[OPTIONS]] 414------------------ 415... 416 417OUTPUT 418------ 419... 420 421 422GIT 423--- 424Part of the linkgit:git[1] suite 425.... 426 427The most important pieces of this to note are the file header, underlined by =, 428the NAME section, and the SYNOPSIS, which would normally contain the grammar if 429your command took arguments. Try to use well-established manpage headers so your 430documentation is consistent with other Git and UNIX manpages; this makes life 431easier for your user, who can skip to the section they know contains the 432information they need. 433 434Now that you've written your manpage, you'll need to build it explicitly. We 435convert your AsciiDoc to troff which is man-readable like so: 436 437---- 438$ make all doc 439$ man Documentation/git-psuh.1 440---- 441 442or 443 444---- 445$ make -C Documentation/ git-psuh.1 446$ man Documentation/git-psuh.1 447---- 448 449NOTE: You may need to install the package `asciidoc` to get this to work. 450 451While this isn't as satisfying as running through `git help`, you can at least 452check that your help page looks right. 453 454You can also check that the documentation coverage is good (that is, the project 455sees that your command has been implemented as well as documented) by running 456`make check-docs` from the top-level. 457 458Go ahead and commit your new documentation change. 459 460[[add-usage]] 461=== Adding Usage Text 462 463Try and run `./bin-wrappers/git psuh -h`. Your command should crash at the end. 464That's because `-h` is a special case which your command should handle by 465printing usage. 466 467Take a look at `Documentation/technical/api-parse-options.txt`. This is a handy 468tool for pulling out options you need to be able to handle, and it takes a 469usage string. 470 471In order to use it, we'll need to prepare a NULL-terminated usage string and a 472`builtin_psuh_options` array. Add a line to `#include "parse-options.h"`. 473 474At global scope, add your usage: 475 476---- 477static const char * const psuh_usage[] = { 478 N_("git psuh"), 479 NULL, 480}; 481---- 482 483Then, within your `cmd_psuh()` implementation, we can declare and populate our 484`option` struct. Ours is pretty boring but you can add more to it if you want to 485explore `parse_options()` in more detail: 486 487---- 488 struct option options[] = { 489 OPT_END() 490 }; 491---- 492 493Finally, before you print your args and prefix, add the call to 494`parse-options()`: 495 496---- 497 argc = parse_options(argc, argv, prefix, options, psuh_usage, 0); 498---- 499 500This call will modify your `argv` parameter. It will strip the options you 501specified in `options` from `argv` and the locations pointed to from `options` 502entries will be updated. Be sure to replace your `argc` with the result from 503`parse_options()`, or you will be confused if you try to parse `argv` later. 504 505It's worth noting the special argument `--`. As you may be aware, many Unix 506commands use `--` to indicate "end of named parameters" - all parameters after 507the `--` are interpreted merely as positional arguments. (This can be handy if 508you want to pass as a parameter something which would usually be interpreted as 509a flag.) `parse_options()` will terminate parsing when it reaches `--` and give 510you the rest of the options afterwards, untouched. 511 512Build again. Now, when you run with `-h`, you should see your usage printed and 513your command terminated before anything else interesting happens. Great! 514 515Go ahead and commit this one, too. 516 517[[testing]] 518== Testing 519 520It's important to test your code - even for a little toy command like this one. 521Moreover, your patch won't be accepted into the Git tree without tests. Your 522tests should: 523 524* Illustrate the current behavior of the feature 525* Prove the current behavior matches the expected behavior 526* Ensure the externally-visible behavior isn't broken in later changes 527 528So let's write some tests. 529 530Related reading: `t/README` 531 532[[overview-test-structure]] 533=== Overview of Testing Structure 534 535The tests in Git live in `t/` and are named with a 4-digit decimal number using 536the schema shown in the Naming Tests section of `t/README`. 537 538[[write-new-test]] 539=== Writing Your Test 540 541Since this a toy command, let's go ahead and name the test with t9999. However, 542as many of the family/subcmd combinations are full, best practice seems to be 543to find a command close enough to the one you've added and share its naming 544space. 545 546Create a new file `t/t9999-psuh-tutorial.sh`. Begin with the header as so (see 547"Writing Tests" and "Source 'test-lib.sh'" in `t/README`): 548 549---- 550#!/bin/sh 551 552test_description='git-psuh test 553 554This test runs git-psuh and makes sure it does not crash.' 555 556. ./test-lib.sh 557---- 558 559Tests are framed inside of a `test_expect_success` in order to output TAP 560formatted results. Let's make sure that `git psuh` doesn't exit poorly and does 561mention the right animal somewhere: 562 563---- 564test_expect_success 'runs correctly with no args and good output' ' 565 git psuh >actual && 566 test_i18ngrep Pony actual 567' 568---- 569 570Indicate that you've run everything you wanted by adding the following at the 571bottom of your script: 572 573---- 574test_done 575---- 576 577Make sure you mark your test script executable: 578 579---- 580$ chmod +x t/t9999-psuh-tutorial.sh 581---- 582 583You can get an idea of whether you created your new test script successfully 584by running `make -C t test-lint`, which will check for things like test number 585uniqueness, executable bit, and so on. 586 587[[local-test]] 588=== Running Locally 589 590Let's try and run locally: 591 592---- 593$ make 594$ cd t/ && prove t9999-psuh-tutorial.sh 595---- 596 597You can run the full test suite and ensure `git-psuh` didn't break anything: 598 599---- 600$ cd t/ 601$ prove -j$(nproc) --shuffle t[0-9]*.sh 602---- 603 604NOTE: You can also do this with `make test` or use any testing harness which can 605speak TAP. `prove` can run concurrently. `shuffle` randomizes the order the 606tests are run in, which makes them resilient against unwanted inter-test 607dependencies. `prove` also makes the output nicer. 608 609Go ahead and commit this change, as well. 610 611[[ready-to-share]] 612== Getting Ready to Share 613 614You may have noticed already that the Git project performs its code reviews via 615emailed patches, which are then applied by the maintainer when they are ready 616and approved by the community. The Git project does not accept patches from 617pull requests, and the patches emailed for review need to be formatted a 618specific way. At this point the tutorial diverges, in order to demonstrate two 619different methods of formatting your patchset and getting it reviewed. 620 621The first method to be covered is GitGitGadget, which is useful for those 622already familiar with GitHub's common pull request workflow. This method 623requires a GitHub account. 624 625The second method to be covered is `git send-email`, which can give slightly 626more fine-grained control over the emails to be sent. This method requires some 627setup which can change depending on your system and will not be covered in this 628tutorial. 629 630Regardless of which method you choose, your engagement with reviewers will be 631the same; the review process will be covered after the sections on GitGitGadget 632and `git send-email`. 633 634[[howto-ggg]] 635== Sending Patches via GitGitGadget 636 637One option for sending patches is to follow a typical pull request workflow and 638send your patches out via GitGitGadget. GitGitGadget is a tool created by 639Johannes Schindelin to make life as a Git contributor easier for those used to 640the GitHub PR workflow. It allows contributors to open pull requests against its 641mirror of the Git project, and does some magic to turn the PR into a set of 642emails and send them out for you. It also runs the Git continuous integration 643suite for you. It's documented at http://gitgitgadget.github.io. 644 645[[create-fork]] 646=== Forking `git/git` on GitHub 647 648Before you can send your patch off to be reviewed using GitGitGadget, you will 649need to fork the Git project and upload your changes. First thing - make sure 650you have a GitHub account. 651 652Head to the https://github.com/git/git[GitHub mirror] and look for the Fork 653button. Place your fork wherever you deem appropriate and create it. 654 655[[upload-to-fork]] 656=== Uploading to Your Own Fork 657 658To upload your branch to your own fork, you'll need to add the new fork as a 659remote. You can use `git remote -v` to show the remotes you have added already. 660From your new fork's page on GitHub, you can press "Clone or download" to get 661the URL; then you need to run the following to add, replacing your own URL and 662remote name for the examples provided: 663 664---- 665$ git remote add remotename git@github.com:remotename/git.git 666---- 667 668or to use the HTTPS URL: 669 670---- 671$ git remote add remotename https://github.com/remotename/git/.git 672---- 673 674Run `git remote -v` again and you should see the new remote showing up. 675`git fetch remotename` (with the real name of your remote replaced) in order to 676get ready to push. 677 678Next, double-check that you've been doing all your development in a new branch 679by running `git branch`. If you didn't, now is a good time to move your new 680commits to their own branch. 681 682As mentioned briefly at the beginning of this document, we are basing our work 683on `master`, so go ahead and update as shown below, or using your preferred 684workflow. 685 686---- 687$ git checkout master 688$ git pull -r 689$ git rebase master psuh 690---- 691 692Finally, you're ready to push your new topic branch! (Due to our branch and 693command name choices, be careful when you type the command below.) 694 695---- 696$ git push remotename psuh 697---- 698 699Now you should be able to go and check out your newly created branch on GitHub. 700 701[[send-pr-ggg]] 702=== Sending a PR to GitGitGadget 703 704In order to have your code tested and formatted for review, you need to start by 705opening a Pull Request against `gitgitgadget/git`. Head to 706https://github.com/gitgitgadget/git and open a PR either with the "New pull 707request" button or the convenient "Compare & pull request" button that may 708appear with the name of your newly pushed branch. 709 710Review the PR's title and description, as it's used by GitGitGadget as the cover 711letter for your change. When you're happy, submit your pull request. 712 713[[run-ci-ggg]] 714=== Running CI and Getting Ready to Send 715 716If it's your first time using GitGitGadget (which is likely, as you're using 717this tutorial) then someone will need to give you permission to use the tool. 718As mentioned in the GitGitGadget documentation, you just need someone who 719already uses it to comment on your PR with `/allow <username>`. GitGitGadget 720will automatically run your PRs through the CI even without the permission given 721but you will not be able to `/submit` your changes until someone allows you to 722use the tool. 723 724If the CI fails, you can update your changes with `git rebase -i` and push your 725branch again: 726 727---- 728$ git push -f remotename psuh 729---- 730 731In fact, you should continue to make changes this way up until the point when 732your patch is accepted into `next`. 733 734//// 735TODO https://github.com/gitgitgadget/gitgitgadget/issues/83 736It'd be nice to be able to verify that the patch looks good before sending it 737to everyone on Git mailing list. 738[[check-work-ggg]] 739=== Check Your Work 740//// 741 742[[send-mail-ggg]] 743=== Sending Your Patches 744 745Now that your CI is passing and someone has granted you permission to use 746GitGitGadget with the `/allow` command, sending out for review is as simple as 747commenting on your PR with `/submit`. 748 749[[responding-ggg]] 750=== Updating With Comments 751 752Skip ahead to <<reviewing,Responding to Reviews>> for information on how to 753reply to review comments you will receive on the mailing list. 754 755Once you have your branch again in the shape you want following all review 756comments, you can submit again: 757 758---- 759$ git push -f remotename psuh 760---- 761 762Next, go look at your pull request against GitGitGadget; you should see the CI 763has been kicked off again. Now while the CI is running is a good time for you 764to modify your description at the top of the pull request thread; it will be 765used again as the cover letter. You should use this space to describe what 766has changed since your previous version, so that your reviewers have some idea 767of what they're looking at. When the CI is done running, you can comment once 768more with `/submit` - GitGitGadget will automatically add a v2 mark to your 769changes. 770 771[[howto-git-send-email]] 772== Sending Patches with `git send-email` 773 774If you don't want to use GitGitGadget, you can also use Git itself to mail your 775patches. Some benefits of using Git this way include finer grained control of 776subject line (for example, being able to use the tag [RFC PATCH] in the subject) 777and being able to send a ``dry run'' mail to yourself to ensure it all looks 778good before going out to the list. 779 780[[setup-git-send-email]] 781=== Prerequisite: Setting Up `git send-email` 782 783Configuration for `send-email` can vary based on your operating system and email 784provider, and so will not be covered in this tutorial, beyond stating that in 785many distributions of Linux, `git-send-email` is not packaged alongside the 786typical `git` install. You may need to install this additional package; there 787are a number of resources online to help you do so. You will also need to 788determine the right way to configure it to use your SMTP server; again, as this 789configuration can change significantly based on your system and email setup, it 790is out of scope for the context of this tutorial. 791 792[[format-patch]] 793=== Preparing Initial Patchset 794 795Sending emails with Git is a two-part process; before you can prepare the emails 796themselves, you'll need to prepare the patches. Luckily, this is pretty simple: 797 798---- 799$ git format-patch --cover-letter -o psuh/ master..psuh 800---- 801 802The `--cover-letter` parameter tells `format-patch` to create a cover letter 803template for you. You will need to fill in the template before you're ready 804to send - but for now, the template will be next to your other patches. 805 806The `-o psuh/` parameter tells `format-patch` to place the patch files into a 807directory. This is useful because `git send-email` can take a directory and 808send out all the patches from there. 809 810`master..psuh` tells `format-patch` to generate patches for the difference 811between `master` and `psuh`. It will make one patch file per commit. After you 812run, you can go have a look at each of the patches with your favorite text 813editor and make sure everything looks alright; however, it's not recommended to 814make code fixups via the patch file. It's a better idea to make the change the 815normal way using `git rebase -i` or by adding a new commit than by modifying a 816patch. 817 818NOTE: Optionally, you can also use the `--rfc` flag to prefix your patch subject 819with ``[RFC PATCH]'' instead of ``[PATCH]''. RFC stands for ``request for 820comments'' and indicates that while your code isn't quite ready for submission, 821you'd like to begin the code review process. This can also be used when your 822patch is a proposal, but you aren't sure whether the community wants to solve 823the problem with that approach or not - to conduct a sort of design review. You 824may also see on the list patches marked ``WIP'' - this means they are incomplete 825but want reviewers to look at what they have so far. You can add this flag with 826`--subject-prefix=WIP`. 827 828Check and make sure that your patches and cover letter template exist in the 829directory you specified - you're nearly ready to send out your review! 830 831[[cover-letter]] 832=== Preparing Email 833 834In addition to an email per patch, the Git community also expects your patches 835to come with a cover letter, typically with a subject line [PATCH 0/x] (where 836x is the number of patches you're sending). Since you invoked `format-patch` 837with `--cover-letter`, you've already got a template ready. Open it up in your 838favorite editor. 839 840You should see a number of headers present already. Check that your `From:` 841header is correct. Then modify your `Subject:` to something which succinctly 842covers the purpose of your entire topic branch, for example: 843 844---- 845Subject: [PATCH 0/7] adding the 'psuh' command 846---- 847 848Make sure you retain the ``[PATCH 0/X]'' part; that's what indicates to the Git 849community that this email is the beginning of a review, and many reviewers 850filter their email for this type of flag. 851 852You'll need to add some extra parameters when you invoke `git send-email` to add 853the cover letter. 854 855Next you'll have to fill out the body of your cover letter. This is an important 856component of change submission as it explains to the community from a high level 857what you're trying to do, and why, in a way that's more apparent than just 858looking at your diff. Be sure to explain anything your diff doesn't make clear 859on its own. 860 861Here's an example body for `psuh`: 862 863---- 864Our internal metrics indicate widespread interest in the command 865git-psuh - that is, many users are trying to use it, but finding it is 866unavailable, using some unknown workaround instead. 867 868The following handful of patches add the psuh command and implement some 869handy features on top of it. 870 871This patchset is part of the MyFirstContribution tutorial and should not 872be merged. 873---- 874 875The template created by `git format-patch --cover-letter` includes a diffstat. 876This gives reviewers a summary of what they're in for when reviewing your topic. 877The one generated for `psuh` from the sample implementation looks like this: 878 879---- 880 Documentation/git-psuh.txt | 40 +++++++++++++++++++++ 881 Makefile | 1 + 882 builtin.h | 1 + 883 builtin/psuh.c | 73 ++++++++++++++++++++++++++++++++++++++ 884 git.c | 1 + 885 t/t9999-psuh-tutorial.sh | 12 +++++++ 886 6 files changed, 128 insertions(+) 887 create mode 100644 Documentation/git-psuh.txt 888 create mode 100644 builtin/psuh.c 889 create mode 100755 t/t9999-psuh-tutorial.sh 890---- 891 892Finally, the letter will include the version of Git used to generate the 893patches. You can leave that string alone. 894 895[[sending-git-send-email]] 896=== Sending Email 897 898At this point you should have a directory `psuh/` which is filled with your 899patches and a cover letter. Time to mail it out! You can send it like this: 900 901---- 902$ git send-email --to=target@example.com psuh/*.patch 903---- 904 905NOTE: Check `git help send-email` for some other options which you may find 906valuable, such as changing the Reply-to address or adding more CC and BCC lines. 907 908NOTE: When you are sending a real patch, it will go to git@vger.kernel.org - but 909please don't send your patchset from the tutorial to the real mailing list! For 910now, you can send it to yourself, to make sure you understand how it will look. 911 912After you run the command above, you will be presented with an interactive 913prompt for each patch that's about to go out. This gives you one last chance to 914edit or quit sending something (but again, don't edit code this way). Once you 915press `y` or `a` at these prompts your emails will be sent! Congratulations! 916 917Awesome, now the community will drop everything and review your changes. (Just 918kidding - be patient!) 919 920[[v2-git-send-email]] 921=== Sending v2 922 923Skip ahead to <<reviewing,Responding to Reviews>> for information on how to 924handle comments from reviewers. Continue this section when your topic branch is 925shaped the way you want it to look for your patchset v2. 926 927When you're ready with the next iteration of your patch, the process is fairly 928similar. 929 930First, generate your v2 patches again: 931 932---- 933$ git format-patch -v2 --cover-letter -o psuh/ master..psuh 934---- 935 936This will add your v2 patches, all named like `v2-000n-my-commit-subject.patch`, 937to the `psuh/` directory. You may notice that they are sitting alongside the v1 938patches; that's fine, but be careful when you are ready to send them. 939 940Edit your cover letter again. Now is a good time to mention what's different 941between your last version and now, if it's something significant. You do not 942need the exact same body in your second cover letter; focus on explaining to 943reviewers the changes you've made that may not be as visible. 944 945You will also need to go and find the Message-Id of your previous cover letter. 946You can either note it when you send the first series, from the output of `git 947send-email`, or you can look it up on the 948https://public-inbox.org/git[mailing list]. Find your cover letter in the 949archives, click on it, then click "permalink" or "raw" to reveal the Message-Id 950header. It should match: 951 952---- 953Message-Id: <foo.12345.author@example.com> 954---- 955 956Your Message-Id is `<foo.12345.author@example.com>`. This example will be used 957below as well; make sure to replace it with the correct Message-Id for your 958**previous cover letter** - that is, if you're sending v2, use the Message-Id 959from v1; if you're sending v3, use the Message-Id from v2. 960 961While you're looking at the email, you should also note who is CC'd, as it's 962common practice in the mailing list to keep all CCs on a thread. You can add 963these CC lines directly to your cover letter with a line like so in the header 964(before the Subject line): 965 966---- 967CC: author@example.com, Othe R <other@example.com> 968---- 969 970Now send the emails again, paying close attention to which messages you pass in 971to the command: 972 973---- 974$ git send-email --to=target@example.com 975 --in-reply-to="<foo.12345.author@example.com>" 976 psuh/v2* 977---- 978 979[[single-patch]] 980=== Bonus Chapter: One-Patch Changes 981 982In some cases, your very small change may consist of only one patch. When that 983happens, you only need to send one email. Your commit message should already be 984meaningful and explain at a high level the purpose (what is happening and why) 985of your patch, but if you need to supply even more context, you can do so below 986the `---` in your patch. Take the example below, which was generated with `git 987format-patch` on a single commit, and then edited to add the content between 988the `---` and the diffstat. 989 990---- 991From 1345bbb3f7ac74abde040c12e737204689a72723 Mon Sep 17 00:00:00 2001 992From: A U Thor <author@example.com> 993Date: Thu, 18 Apr 2019 15:11:02 -0700 994Subject: [PATCH] README: change the grammar 995 996I think it looks better this way. This part of the commit message will 997end up in the commit-log. 998 999Signed-off-by: A U Thor <author@example.com>1000---1001Let's have a wild discussion about grammar on the mailing list. This1002part of my email will never end up in the commit log. Here is where I1003can add additional context to the mailing list about my intent, outside1004of the context of the commit log. This section was added after `git1005format-patch` was run, by editing the patch file in a text editor.10061007 README.md | 2 +-1008 1 file changed, 1 insertion(+), 1 deletion(-)10091010diff --git a/README.md b/README.md1011index 88f126184c..38da593a60 1006441012--- a/README.md1013+++ b/README.md1014@@ -3,7 +3,7 @@1015 Git - fast, scalable, distributed revision control system1016 =========================================================10171018-Git is a fast, scalable, distributed revision control system with an1019+Git is a fast, scalable, and distributed revision control system with an1020 unusually rich command set that provides both high-level operations1021 and full access to internals.10221023--10242.21.0.392.gf8f6787159e-goog1025----10261027[[now-what]]1028== My Patch Got Emailed - Now What?10291030[[reviewing]]1031=== Responding to Reviews10321033After a few days, you will hopefully receive a reply to your patchset with some1034comments. Woohoo! Now you can get back to work.10351036It's good manners to reply to each comment, notifying the reviewer that you have1037made the change requested, feel the original is better, or that the comment1038inspired you to do something a new way which is superior to both the original1039and the suggested change. This way reviewers don't need to inspect your v2 to1040figure out whether you implemented their comment or not.10411042If you are going to push back on a comment, be polite and explain why you feel1043your original is better; be prepared that the reviewer may still disagree with1044you, and the rest of the community may weigh in on one side or the other. As1045with all code reviews, it's important to keep an open mind to doing something a1046different way than you originally planned; other reviewers have a different1047perspective on the project than you do, and may be thinking of a valid side1048effect which had not occurred to you. It is always okay to ask for clarification1049if you aren't sure why a change was suggested, or what the reviewer is asking1050you to do.10511052Make sure your email client has a plaintext email mode and it is turned on; the1053Git list rejects HTML email. Please also follow the mailing list etiquette1054outlined in the1055https://kernel.googlesource.com/pub/scm/git/git/+/todo/MaintNotes[Maintainer's1056Note], which are similar to etiquette rules in most open source communities1057surrounding bottom-posting and inline replies.10581059When you're making changes to your code, it is cleanest - that is, the resulting1060commits are easiest to look at - if you use `git rebase -i` (interactive1061rebase). Take a look at this1062https://www.oreilly.com/library/view/git-pocket-guide/9781449327507/ch10.html[overview]1063from O'Reilly. The general idea is to modify each commit which requires changes;1064this way, instead of having a patch A with a mistake, a patch B which was fine1065and required no upstream reviews in v1, and a patch C which fixes patch A for1066v2, you can just ship a v2 with a correct patch A and correct patch B. This is1067changing history, but since it's local history which you haven't shared with1068anyone, that is okay for now! (Later, it may not make sense to do this; take a1069look at the section below this one for some context.)10701071[[after-approval]]1072=== After Review Approval10731074The Git project has four integration branches: `pu`, `next`, `master`, and1075`maint`. Your change will be placed into `pu` fairly early on by the maintainer1076while it is still in the review process; from there, when it is ready for wider1077testing, it will be merged into `next`. Plenty of early testers use `next` and1078may report issues. Eventually, changes in `next` will make it to `master`,1079which is typically considered stable. Finally, when a new release is cut,1080`maint` is used to base bugfixes onto. As mentioned at the beginning of this1081document, you can read `Documents/SubmittingPatches` for some more info about1082the use of the various integration branches.10831084Back to now: your code has been lauded by the upstream reviewers. It is perfect.1085It is ready to be accepted. You don't need to do anything else; the maintainer1086will merge your topic branch to `next` and life is good.10871088However, if you discover it isn't so perfect after this point, you may need to1089take some special steps depending on where you are in the process.10901091If the maintainer has announced in the "What's cooking in git.git" email that1092your topic is marked for `next` - that is, that they plan to merge it to `next`1093but have not yet done so - you should send an email asking the maintainer to1094wait a little longer: "I've sent v4 of my series and you marked it for `next`,1095but I need to change this and that - please wait for v5 before you merge it."10961097If the topic has already been merged to `next`, rather than modifying your1098patches with `git rebase -i`, you should make further changes incrementally -1099that is, with another commit, based on top of the maintainer's topic branch as1100detailed in https://github.com/gitster/git. Your work is still in the same topic1101but is now incremental, rather than a wholesale rewrite of the topic branch.11021103The topic branches in the maintainer's GitHub are mirrored in GitGitGadget, so1104if you're sending your reviews out that way, you should be sure to open your PR1105against the appropriate GitGitGadget/Git branch.11061107If you're using `git send-email`, you can use it the same way as before, but you1108should generate your diffs from `<topic>..<mybranch>` and base your work on1109`<topic>` instead of `master`.