docs/developer/TypicalGitUsage.mdwn

   1 [[!meta title="Mastering the DragonFly git repository"]]
   2
   3 [[!toc  levels=2]]
   4 ## Clone the repository
   5
   6
   7 First you go in your work directory and clone the DragonFly repository. While ***crater*** is the official repo, you are urged to use one of our (generally much faster) mirrors instead.
   8
   9     > git clone -o chlamydia git://chlamydia.fs.ei.tum.de/dragonfly.git
  10
  11 If you are a committer, you should create a ***remote*** entry for pushing to ***crater***:
  12
  13
  14     > git remote add crater ssh://crater.dragonflybsd.org/repository/git/dragonfly.git
  15
  16 Clone creates remote-tracking branches for all branches in the parent repo and creates a local  **master**  branch from the remote  **master**  branch.
  17
  18     > git branch -a
  19
  20
  21     * master
  22       chlamydia/DragonFly_RELEASE_1_10
  23       chlamydia/DragonFly_RELEASE_1_12
  24       chlamydia/DragonFly_RELEASE_1_2
  25       chlamydia/DragonFly_RELEASE_1_4
  26       chlamydia/DragonFly_RELEASE_1_6
  27       chlamydia/DragonFly_RELEASE_1_8
  28       chlamydia/DragonFly_RELEASE_2_0
  29       chlamydia/HEAD
  30       chlamydia/master
  31       chlamydia/repo/hooks
  32       chlamydia/vendor/ATHEROS
  33       [...]
  34       chlamydia/vendor/ZLIB
  35
  36 ## Prepare patches
  37
  38 If you (as a non-developer) made some changes to the DragonFly source and want to get them included in the main repository, send your patches to submit@lists.dragonflybsd.org. git assists you in creating patches which are easy to handle for the developers.
  39
  40 ### Example
  41
  42  **Note:**  The change in this example is completely useless, it only serves demonstration purposes!
  43
  44
  45
  46 At first edit the files you want to change:
  47
  48     > vim README
  49
  50 Then review your changes with `git diff`:
  51
  52
  53
  54     > git diff
  55     diff --git a/README b/README
  56     index 495a262..6a95d1f 100644
  57     --- a/README
  58     +++ b/README
  59     @@ -59,7 +59,7 @@ lib           System libraries
  60
  61      libexec                System daemons.
  62
  63     -nrelease       Framework for building the ***live*** CD image.
  64     +nrelease       Framework for building the ***live CD*** image.
  65
  66      sbin           System commands.
  67
  68
  69 If you are satisfied with your changes, commit them.   **Note:**  The first line of your commit message should describe your change in a small sentence.  Add more details after one newline.
  70
  71
  72
  73     > git commit -a
  74     ".git/COMMIT_EDITMSG" 10L, 342C written
  75     Created commit cbb871b: Change parentheses
  76      1 files changed, 1 insertions(+), 1 deletions(-)
  77
  78 Now you can use `git format-patch` to generate a patch file.  This file is ready for submission to submit@. `git format-patch` will generate one file for every commit you did.
  79
  80
  81
  82     > git format-patch origin
  83     0001-Change-parentheses.patch
  84     > cat 0001-Change-parentheses.patch
  85     From cbb871b4588c695f000bc701b4f3c16a0a518991 Mon Sep 17 00:00:00 2001
  86     From: Matthias Schmidt <matthiasdragonflybsd.org>
  87     Date: Tue, 2 Dec 2008 09:54:47 +0100
  88     Subject: [PATCH] Change parentheses
  89
  90
  91     ---
  92      README |    2 +-
  93      1 files changed, 1 insertions(+), 1 deletions(-)
  94
  95
  96
  97     diff --git a/README b/README
  98     index 495a262..6a95d1f 100644
  99     --- a/README
 100     +++ b/README
 101     @@ -59,7 +59,7 @@ lib           System libraries.
 102
 103      libexec                System daemons.
 104
 105     -nrelease       Framework for building the ***live*** CD image.
 106     +nrelease       Framework for building the ***live CD*** image.
 107
 108      sbin           System commands.
 109     --
 110     1.6.0.2
 111
 112
 113
 114 Attach the generated files to a mail and submit it.  Write some lines about your intention and why you changed what ...
 115
 116
 117
 118 ## Working with branches
 119
 120 It is  **not**  recommended to work directly in your  **master**  branch, except maybe for one-liners. Branches in git are very cheap, so just keep your  **master**  branch pure, and always work on a different local branch.
 121
 122 Say you want to work on a simple change. Just create a temporary branch, make the change and commit it.
 123
 124
 125
 126     > git checkout -b work      # you're now in the work branch
 127     > vim what/ever.c
 128     > git commit -a
 129
 130 Now, you can switch back to  **master** , merge in the changes in your  **work**  branch and push away:
 131
 132
 133
 134     > git checkout master      # you're now in the master branch
 135     > git merge work           # now master has your changes
 136
 137 Afterwards, you may (or not, if you want to do further development) want to delete the  **work**  branch by
 138
 139
 140     > git branch -d work
 141
 142 For more complex changes, you probably want to create a longer-lived branch. For example
 143
 144
 145     > git checkout -b myfeature
 146
 147 You can work in the  **myfeature**  branch until your feature is ready. You can commit there as often as you like. If your work goes on for a significant amount of time, you will want to merge with the upstream  **master**  from time to time. It is recommended that you use git rebase, so that the merge points won't show up in the repo history on crater (they don't really add much information). For this, you'd do:
 148
 149
 150     > git checkout master
 151     > git pull
 152     > git checkout myfeature
 153     > git rebase master
 154
 155
 156 ## Push your work upstream
 157
 158 When you judge that your code is ready for inclusion in mainline, you can merge it into your local  **master**  branch and push away:
 159
 160
 161
 162     > git checkout master
 163     > git merge myfeature
 164     > git push crater
 165
 166
 167 as the command will not push any branch that is not in the remote repository.
 168