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