github.com/nf/docker@v1.8.1/docs/project/set-up-git.md (about)

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