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.
   8
   9     > git clone git://git.dragonflybsd.org/dragonfly.git
  10    Or even better on a DragonFly system just use make
  11
  12     > cd /usr
  13     > make src-create
  14
  15 If you are a committer, you should create a ***remote*** entry for pushing to ***crater***:
  16
  17
  18     > git remote add crater ssh://crater.dragonflybsd.org/repository/git/dragonfly.git
  19
  20 Clone creates remote-tracking branches for all branches in the parent repo and creates a local  **master**  branch from the remote  **master**  branch.
  21
  22     > git branch -a
  23
  24
  25     * master
  26       chlamydia/DragonFly_RELEASE_1_10
  27       chlamydia/DragonFly_RELEASE_1_12
  28       chlamydia/DragonFly_RELEASE_1_2
  29       chlamydia/DragonFly_RELEASE_1_4
  30       chlamydia/DragonFly_RELEASE_1_6
  31       chlamydia/DragonFly_RELEASE_1_8
  32       chlamydia/DragonFly_RELEASE_2_0
  33       chlamydia/HEAD
  34       chlamydia/master
  35       chlamydia/repo/hooks
  36       chlamydia/vendor/ATHEROS
  37       [...]
  38       chlamydia/vendor/ZLIB
  39
  40 ## Prepare patches
  41
  42 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.
  43
  44 ### Example
  45
  46  **Note:**  The change in this example is completely useless, it only serves demonstration purposes!
  47
  48
  49
  50 At first edit the files you want to change:
  51
  52     > vim README
  53
  54 Then review your changes with `git diff`:
  55
  56
  57
  58     > git diff
  59     diff --git a/README b/README
  60     index 495a262..6a95d1f 100644
  61     --- a/README
  62     +++ b/README
  63     @@ -59,7 +59,7 @@ lib           System libraries
  64
  65      libexec                System daemons.
  66
  67     -nrelease       Framework for building the ***live*** CD image.
  68     +nrelease       Framework for building the ***live CD*** image.
  69
  70      sbin           System commands.
  71
  72
  73 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.
  74
  75
  76
  77     > git commit -a
  78     ".git/COMMIT_EDITMSG" 10L, 342C written
  79     Created commit cbb871b: Change parentheses
  80      1 files changed, 1 insertions(+), 1 deletions(-)
  81
  82 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.
  83
  84
  85
  86     > git format-patch origin
  87     0001-Change-parentheses.patch
  88     > cat 0001-Change-parentheses.patch
  89     From cbb871b4588c695f000bc701b4f3c16a0a518991 Mon Sep 17 00:00:00 2001
  90     From: Matthias Schmidt <matthiasdragonflybsd.org>
  91     Date: Tue, 2 Dec 2008 09:54:47 +0100
  92     Subject: [PATCH] Change parentheses
  93
  94
  95     ---
  96      README |    2 +-
  97      1 files changed, 1 insertions(+), 1 deletions(-)
  98
  99
 100
 101     diff --git a/README b/README
 102     index 495a262..6a95d1f 100644
 103     --- a/README
 104     +++ b/README
 105     @@ -59,7 +59,7 @@ lib           System libraries.
 106
 107      libexec                System daemons.
 108
 109     -nrelease       Framework for building the ***live*** CD image.
 110     +nrelease       Framework for building the ***live CD*** image.
 111
 112      sbin           System commands.
 113     --
 114     1.6.0.2
 115
 116
 117
 118 Attach the generated files to a mail and submit it.  Write some lines about your intention and why you changed what ...
 119
 120
 121
 122 ## Working with branches
 123
 124 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.
 125
 126 Say you want to work on a simple change. Just create a temporary branch, make the change and commit it.
 127
 128
 129
 130     > git checkout -b work      # you're now in the work branch
 131     > vim what/ever.c
 132     > git commit -a
 133
 134 Now, you can switch back to  **master** , merge in the changes in your  **work**  branch and push away:
 135
 136
 137
 138     > git checkout master      # you're now in the master branch
 139     > git merge work           # now master has your changes
 140
 141 Afterwards, you may (or not, if you want to do further development) want to delete the  **work**  branch by
 142
 143
 144     > git branch -d work
 145
 146 For more complex changes, you probably want to create a longer-lived branch. For example
 147
 148
 149     > git checkout -b myfeature
 150
 151 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:
 152
 153
 154     > git checkout master
 155     > git pull
 156     > git checkout myfeature
 157     > git rebase master
 158
 159
 160 ## Push your work upstream
 161
 162 When you judge that your code is ready for inclusion in mainline, you can merge it into your local  **master**  branch and push away:
 163
 164
 165
 166     > git checkout master
 167     > git merge myfeature
 168     > git push crater
 169
 170
 171 as the command will not push any branch that is not in the remote repository.
 172