docs/developer/TypicalGitUsage.mdwn

   1 [[!meta title="Mastering the DragonFly git repository"]]
   2
   3 [[!toc  levels=2]]
   4
   5 ## Clone the repository
   6
   7 Look at the [[download]] page on how to clone the DragonFly repository. ***Note***: Please use a git mirror to reduce the bandwidth on the main servers.
   8
   9 ## Prepare patches
  10
  11 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`.
  12 In order to be able to do that, you need to have yourself and the email address you are using registered with the <http://bugs.dragonflybsd.org/> bug/issue tracker; otherwise, your contribution will get silently dropped.
  13
  14 Git assists you in creating patches which are easy to handle for the developers.
  15 ### Example
  16
  17  **Note:**  The change in this example is completely useless, it only serves demonstration purposes!
  18
  19
  20
  21 At first edit the files you want to change:
  22
  23     > vim README
  24
  25 Then review your changes with `git diff`:
  26
  27
  28
  29     > git diff
  30     diff --git a/README b/README
  31     index 495a262..6a95d1f 100644
  32     --- a/README
  33     +++ b/README
  34     @@ -59,7 +59,7 @@ lib           System libraries
  35
  36      libexec                System daemons.
  37
  38     -nrelease       Framework for building the ***live*** CD image.
  39     +nrelease       Framework for building the ***live CD*** image.
  40
  41      sbin           System commands.
  42
  43
  44 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.
  45
  46
  47
  48     > git commit -a
  49     ".git/COMMIT_EDITMSG" 10L, 342C written
  50     Created commit cbb871b: Change parentheses
  51      1 files changed, 1 insertions(+), 1 deletions(-)
  52
  53 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.
  54
  55
  56
  57     > git format-patch origin/master
  58     0001-Change-parentheses.patch
  59     > cat 0001-Change-parentheses.patch
  60     From cbb871b4588c695f000bc701b4f3c16a0a518991 Mon Sep 17 00:00:00 2001
  61     From: Matthias Schmidt <matthiasdragonflybsd.org>
  62     Date: Tue, 2 Dec 2008 09:54:47 +0100
  63     Subject: [PATCH] Change parentheses
  64
  65
  66     ---
  67      README |    2 +-
  68      1 files changed, 1 insertions(+), 1 deletions(-)
  69
  70
  71
  72     diff --git a/README b/README
  73     index 495a262..6a95d1f 100644
  74     --- a/README
  75     +++ b/README
  76     @@ -59,7 +59,7 @@ lib           System libraries.
  77
  78      libexec                System daemons.
  79
  80     -nrelease       Framework for building the ***live*** CD image.
  81     +nrelease       Framework for building the ***live CD*** image.
  82
  83      sbin           System commands.
  84     --
  85     1.6.0.2
  86
  87
  88
  89 Attach the generated files to a mail and submit it.  Write some lines about your intention and why you changed what ...
  90
  91
  92
  93 ## Working with branches
  94
  95 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.
  96
  97 Say you want to work on a simple change. Just create a temporary branch, make the change and commit it.
  98
  99
 100
 101     > git checkout -b work      # you're now in the work branch
 102     > vim what/ever.c
 103     > git commit -a
 104
 105 Now, you can switch back to  **master** , merge in the changes in your  **work**  branch and push away:
 106
 107
 108
 109     > git checkout master      # you're now in the master branch
 110     > git merge work           # now master has your changes
 111
 112 Afterwards, you may (or not, if you want to do further development) want to delete the  **work**  branch by
 113
 114
 115     > git branch -d work
 116
 117 For more complex changes, you probably want to create a longer-lived branch. For example
 118
 119
 120     > git checkout -b myfeature
 121
 122 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:
 123
 124
 125     > git checkout master
 126     > git pull
 127     > git checkout myfeature
 128     > git rebase master
 129
 130
 131 ## Push your work upstream
 132
 133 When you judge that your code is ready for inclusion in mainline, you can merge it into your local  **master**  branch and push away:
 134
 135
 136
 137     > git checkout master
 138     > git merge myfeature
 139     > git push crater
 140
 141
 142 as the command will not push any branch that is not in the remote repository.
 143