1 2This directory contains tools intended to help committers use git when 3interacting with standard FreeBSD project resources like Differential. 4 5I. arcgit 6 7arcgit is a wrapper script around the arc command line tool that simplifies the 8automatic creation of a series of Differential reviews from a series of git 9commits. The intended workflow is: 10 111. Create a series of commits in git. Each commit will be a separate review, so 12 try to make each commit as self-contained as possible. The series of commits 13 should demonstrate a logical progression towards your end goal. For example, 14 one commit might refactor existing code to expose a new API without changing 15 any current functionality. A subsequent commit could then introduce your new 16 code that uses the new API. 17 18 It usually will not be helpful to present your code in the order in which it 19 was actually written and can actually be harmful. For example, if you 20 introduced a bug early in your development process that you fixed in a 21 subsequent commit, it is a waste of your reviewer's time to have them review 22 old code with known bugs. Instead, it would probably be best to squash the 23 bug fix into the commit that introduced it, so that the bug is never 24 presented to your reviewers in any review. 25 26 The commit headline and commit message will be imported verbatim into 27 Differential, so try to give each commit a meaningful commit message that 28 gives your reviewers the necessary context to understand your change. 29 302. Create your reviews by running this command in your git repo: 31 $ arcgit -r C1~..C2 -R reviewer -T testplan 32 33 C1 should be the first commit that you want reviewed, and C2 should be the 34 last commit that you want reviewed. You may add multiple reviewers by 35 specifying the -R option multiple times. You can CC (AKA subscribe) people 36 to a review with the -C option. Note that if you subscribe a mailing list 37 to a review, the mailing list will be emailed for every comment or change 38 made to each review. Please be judicious when subscribing mailing lists to 39 reviews. It may be better to instead send a single email to the appropriate 40 list announcing all of the reviews and giving a short summary of the change 41 as a whole, along with a link to the individual reviews. 42 433. When you need to make a change and upload it to a review, use the following 44 process. First, check out the branch corresponding to the review (arcgit 45 automatically creates this branch for every review that it creates): 46 47 $ git checkout review_D1234 48 49 Next, make your change and perform whatever testing is necessary. Commit it 50 to your repository with this command: 51 52 $ git commit --fixup HEAD 53 54 You can upload the change to the code review by running this command in your 55 repository while (ensure that you are still on the review_D1234 branch): 56 57 $ arc diff --update D1234 review_D1234_base 58 59 When you run arc, it will pull up your editor and give you a chance to 60 change the message that will be shown in Differential for this upload. It's 61 recommended that you change it from the default "fixup! ...." as that does 62 not give your reviewers an indication of what changes were made. It's not 63 recommended that you give the code review fixes meaningful commit messages 64 directly because we will be using git's autosquash feature in the next step, 65 which depends on the fixup! tag being present. 66 67 Do not merge in other branches, or rebase your review branches at this point. 68 Any changes that are made will show up in your reviews, and that will create 69 extra noise that your reviewers will have to ignore. If a reviewer requests 70 a change that requires your commit to be based off of a later version of 71 head, I would suggest deferring the change from the review and creating a 72 new review with the change once you hit step 5. 73 744. Once the reviews have been approved, you need to prepare your patch series 75 to be committed. This involves squashing the fixes made in code review 76 back into the original commit that they applied to. This gives you a clean 77 series of commits that are ready to be pushed to git. 78 79 First, merge each of your review branches back into your main development 80 branch. For example: 81 82 $ git checkout myfeature_dev 83 $ for branch in review_D1234 review_D1235 review_D1236; do \ 84 git merge $branch || git mergetool -y || break; done 85 86 Next, do an interactive rebase to squash your code review fixes back into the 87 main commit: 88 89 $ git rebase -i -k review_D1234_base 90 91 review_D1234 should be the name of the *first* review that was created for 92 you in step 2. For every commit, your editor will be pulled up and you will 93 be given one last chance to edit your commit message. Make sure that you fill 94 in the "Reviewed by:" tag indicating who accepted the review. This would 95 be a good point to add other tags like MFC after:, Sponsored by:, etc. 96 97 The rebase will not introduce any actual changes to your code if done 98 properly. You can use this command to double-check that no changes were 99 inadvertently made here: 100 101 $ git diff myfeature_dev@{1} 102 1035. Finally, you should get up to date with the latest changes from head: 104 105 $ git pull --rebase origin master 106 107 It is not recommended that you combine this step with the rebase done in the 108 previous step. The reason for this is that if you perform an interactive 109 rebase that changes the commit that you branch from, it becomes much more 110 difficult to use the reflog to confirm that the interactive rebase did not 111 introduce unwanted changes. 112 113 At this point, you are ready to commit your changes to head. The importgit 114 script can be used to import your commits directly into git. 115