github.com/demonoid81/moby@v0.0.0-20200517203328-62dd8e17c460/docs/contributing/set-up-git.md (about) 1 ### Configure Git for contributing 2 3 Work through this page to configure Git and a repository you'll use throughout 4 the Contributor Guide. The work you do further in the guide, depends on the work 5 you do here. 6 7 ## Task 1. Fork and clone the Moby code 8 9 Before contributing, you first fork the Moby code repository. A fork copies 10 a repository at a particular point in time. GitHub tracks for you where a fork 11 originates. 12 13 As you make contributions, you change your fork's code. When you are ready, 14 you make a pull request back to the original Docker repository. If you aren't 15 familiar with this workflow, don't worry, this guide walks you through all the 16 steps. 17 18 To fork and clone Moby: 19 20 1. Open a browser and log into GitHub with your account. 21 22 2. Go to the <a href="https://github.com/moby/moby" 23 target="_blank">moby/moby repository</a>. 24 25 3. Click the "Fork" button in the upper right corner of the GitHub interface. 26 27 ![Branch Signature](images/fork_docker.png) 28 29 GitHub forks the repository to your GitHub account. The original 30 `moby/moby` repository becomes a new fork `YOUR_ACCOUNT/moby` under 31 your account. 32 33 4. Copy your fork's clone URL from GitHub. 34 35 GitHub allows you to use HTTPS or SSH protocols for clones. You can use the 36 `git` command line or clients like Subversion to clone a repository. 37 38 ![Copy clone URL](images/copy_url.png) 39 40 This guide assume you are using the HTTPS protocol and the `git` command 41 line. If you are comfortable with SSH and some other tool, feel free to use 42 that instead. You'll need to convert what you see in the guide to what is 43 appropriate to your tool. 44 45 5. Open a terminal window on your local host and change to your home directory. 46 47 ```bash 48 $ cd ~ 49 ``` 50 51 In Windows, you'll work in your Docker Quickstart Terminal window instead of 52 Powershell or a `cmd` window. 53 54 6. Create a `repos` directory. 55 56 ```bash 57 $ mkdir repos 58 ``` 59 60 7. Change into your `repos` directory. 61 62 ```bash 63 $ cd repos 64 ``` 65 66 8. Clone the fork to your local host into a repository called `moby-fork`. 67 68 ```bash 69 $ git clone https://github.com/moxiegirl/moby.git moby-fork 70 ``` 71 72 Naming your local repo `moby-fork` should help make these instructions 73 easier to follow; experienced coders don't typically change the name. 74 75 9. Change directory into your new `moby-fork` directory. 76 77 ```bash 78 $ cd moby-fork 79 ``` 80 81 Take a moment to familiarize yourself with the repository's contents. List 82 the contents. 83 84 ## Task 2. Set your signature and an upstream remote 85 86 When you contribute to Docker, you must certify you agree with the 87 <a href="http://developercertificate.org/" target="_blank">Developer Certificate of Origin</a>. 88 You indicate your agreement by signing your `git` commits like this: 89 90 ``` 91 Signed-off-by: Pat Smith <pat.smith@email.com> 92 ``` 93 94 To create a signature, you configure your username and email address in Git. 95 You can set these globally or locally on just your `moby-fork` repository. 96 You must sign with your real name. You can sign your git commit automatically 97 with `git commit -s`. Moby does not accept anonymous contributions or contributions 98 through pseudonyms. 99 100 As you change code in your fork, you'll want to keep it in sync with the changes 101 others make in the `moby/moby` repository. To make syncing easier, you'll 102 also add a _remote_ called `upstream` that points to `moby/moby`. A remote 103 is just another project version hosted on the internet or network. 104 105 To configure your username, email, and add a remote: 106 107 1. Change to the root of your `moby-fork` repository. 108 109 ```bash 110 $ cd moby-fork 111 ``` 112 113 2. Set your `user.name` for the repository. 114 115 ```bash 116 $ git config --local user.name "FirstName LastName" 117 ``` 118 119 3. Set your `user.email` for the repository. 120 121 ```bash 122 $ git config --local user.email "emailname@mycompany.com" 123 ``` 124 125 4. Set your local repo to track changes upstream, on the `moby/moby` repository. 126 127 ```bash 128 $ git remote add upstream https://github.com/moby/moby.git 129 ``` 130 131 5. Check the result in your `git` configuration. 132 133 ```bash 134 $ git config --local -l 135 core.repositoryformatversion=0 136 core.filemode=true 137 core.bare=false 138 core.logallrefupdates=true 139 remote.origin.url=https://github.com/moxiegirl/moby.git 140 remote.origin.fetch=+refs/heads/*:refs/remotes/origin/* 141 branch.master.remote=origin 142 branch.master.merge=refs/heads/master 143 user.name=Mary Anthony 144 user.email=mary@docker.com 145 remote.upstream.url=https://github.com/moby/moby.git 146 remote.upstream.fetch=+refs/heads/*:refs/remotes/upstream/* 147 ``` 148 149 To list just the remotes use: 150 151 ```bash 152 $ git remote -v 153 origin https://github.com/moxiegirl/moby.git (fetch) 154 origin https://github.com/moxiegirl/moby.git (push) 155 upstream https://github.com/moby/moby.git (fetch) 156 upstream https://github.com/moby/moby.git (push) 157 ``` 158 159 ## Task 3. Create and push a branch 160 161 As you change code in your fork, make your changes on a repository branch. 162 The branch name should reflect what you are working on. In this section, you 163 create a branch, make a change, and push it up to your fork. 164 165 This branch is just for testing your config for this guide. The changes are part 166 of a dry run, so the branch name will be dry-run-test. To create and push 167 the branch to your fork on GitHub: 168 169 1. Open a terminal and go to the root of your `moby-fork`. 170 171 ```bash 172 $ cd moby-fork 173 ``` 174 175 2. Create a `dry-run-test` branch. 176 177 ```bash 178 $ git checkout -b dry-run-test 179 ``` 180 181 This command creates the branch and switches the repository to it. 182 183 3. Verify you are in your new branch. 184 185 ```bash 186 $ git branch 187 * dry-run-test 188 master 189 ``` 190 191 The current branch has an * (asterisk) marker. So, these results show you 192 are on the right branch. 193 194 4. Create a `TEST.md` file in the repository's root. 195 196 ```bash 197 $ touch TEST.md 198 ``` 199 200 5. Edit the file and add your email and location. 201 202 ![Add your information](images/contributor-edit.png) 203 204 You can use any text editor you are comfortable with. 205 206 6. Save and close the file. 207 208 7. Check the status of your branch. 209 210 ```bash 211 $ git status 212 On branch dry-run-test 213 Untracked files: 214 (use "git add <file>..." to include in what will be committed) 215 216 TEST.md 217 218 nothing added to commit but untracked files present (use "git add" to track) 219 ``` 220 221 You've only changed the one file. It is untracked so far by git. 222 223 8. Add your file. 224 225 ```bash 226 $ git add TEST.md 227 ``` 228 229 That is the only _staged_ file. Stage is fancy word for work that Git is 230 tracking. 231 232 9. Sign and commit your change. 233 234 ```bash 235 $ git commit -s -m "Making a dry run test." 236 [dry-run-test 6e728fb] Making a dry run test 237 1 file changed, 1 insertion(+) 238 create mode 100644 TEST.md 239 ``` 240 241 Commit messages should have a short summary sentence of no more than 50 242 characters. Optionally, you can also include a more detailed explanation 243 after the summary. Separate the summary from any explanation with an empty 244 line. 245 246 10. Push your changes to GitHub. 247 248 ```bash 249 $ git push --set-upstream origin dry-run-test 250 Username for 'https://github.com': moxiegirl 251 Password for 'https://moxiegirl@github.com': 252 ``` 253 254 Git prompts you for your GitHub username and password. Then, the command 255 returns a result. 256 257 ```bash 258 Counting objects: 13, done. 259 Compressing objects: 100% (2/2), done. 260 Writing objects: 100% (3/3), 320 bytes | 0 bytes/s, done. 261 Total 3 (delta 1), reused 0 (delta 0) 262 To https://github.com/moxiegirl/moby.git 263 * [new branch] dry-run-test -> dry-run-test 264 Branch dry-run-test set up to track remote branch dry-run-test from origin. 265 ``` 266 267 11. Open your browser to GitHub. 268 269 12. Navigate to your Moby fork. 270 271 13. Make sure the `dry-run-test` branch exists, that it has your commit, and the 272 commit is signed. 273 274 ![Branch Signature](images/branch-sig.png) 275 276 ## Where to go next 277 278 Congratulations, you have finished configuring both your local host environment 279 and Git for contributing. In the next section you'll [learn how to set up and 280 work in a Moby development container](set-up-dev-env.md).