Skip to content
Newer
Older
100644 223 lines (175 sloc) 7.29 KB
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored Nov 10, 2009
1 ---
2 layout: default
3 title: Using Git
4 ---
5
6 {{ page.title }}
7 ================
8
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored Aug 2, 2011
9 The DataMapper project uses the Git SCM. Committers
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored Nov 10, 2009
10 need to use git to commit their code directly to the main repository.
11
12 This page contains information on getting Git installed, getting source code
13 with Git, and steps for working with Git.
14
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored Aug 3, 2011
15 Also, see these references:
16
17 * [Git - SVN Crash Course](http://git-scm.com/course/svn.html)
18 * [Everyday Git With 20 Commands Or So](http://www.kernel.org/pub/software/scm/git/docs/everyday.html)
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored Nov 10, 2009
19
20 Getting Git for Your System
21 ---------------------------
22
23 You can use an earlier version, but 1.5.x is definitely recommended.
24
25 * MacPorts has `git-core`
26 * Debian has `git-core`; (If you're using Etch, you can get a recent Git version from Backports <a href="http://backports.org/dokuwiki/doku.php?id=instructions">http://backports.org/dokuwiki/do&#8230;</a>)
22056f3 @dkubb Updated git links to point to new official site
dkubb authored Dec 11, 2009
27 * Get the source at <a href="http://git-scm.com/">http://git-scm.com/</a>.
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored Nov 10, 2009
28
29 Setup
30 -----
31
32 Configure Git with your proper name and email. This will display when you submit
33 changes to the DataMapper repository.
34
35 {% highlight bash %}
36 git config --global user.name "My Name"
37 git config --global user.email "my@email"
38 {% endhighlight %}
39
40 If you prefer to use different credentials for different projects, you can also
41 configure the above for a single repository only. See the git documentation.
42
43 Formatting Git Commit Messages
44 ------------------------------
45
46 In general, use an editor to create your commit messages rather than passing
47 them on the command line. The format should be:
48
49 * A hard wrap at 72 characters
50 * A single, short, summary of the commit
51 * Followed by a single blank line
52 * Followed by supporting details
53
54 The supporting details could be a bulleted enumeration or an explanatory
55 paragraph. The single summary line helps folks reviewing commits. An example
56 commit:
57
58 {% highlight bash lineos %}
59 Fixes for Module#make_my_day return values.
60
61 * Return nil when passed ':('
62 * Return true when passed ':)'
63 * Updated specs for #make_my_day for nil argument case
64 * Updated CI excludes.
65 {% endhighlight %}
66
67 Getting the Code
68 ----------------
69
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored Aug 3, 2011
70 DataMapper is hosted at [GitHub](http://github.com/datamapper/).
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored Nov 10, 2009
71 Getting the code is easy once you have git installed but is slightly different
72 depending on your access. In both cases that exact command will put the
73 repository in a local directory called dm. You can give it a different name just
74 by appending it to the command.
75
76 ### New Users and Developers
77
78 {% highlight bash lineos %}
79 git clone git://github.com/datamapper/dm-core.git
80 {% endhighlight %}
81
82 ### Committers with Commit Bit
83
84 {% highlight bash lineos %}
85 git clone git@github.com/datamapper/dm-core.git
86 {% endhighlight %}
87
88 Git Workflow
89 ------------
90
13ca54f @dkubb Fix whiteapace
dkubb authored Apr 1, 2012
91 Working with Git is significantly different than working with
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored Aug 3, 2011
92 SVN. In particular, although similar, git pull is not svn
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored Nov 10, 2009
93 update, git push is not svn commit, and git add is not svn add. If you are a
ed25960 @postmodern Misc formatting and wording changes.
postmodern authored Aug 3, 2011
94 SVN user, be sure to read the man pages for the
6f27760 @myabc Convert datamapper.org site to Jekyll, Markdown
myabc authored Nov 10, 2009
95 different git commands.</p>
96
97 The following workflow is recommended by Rein and is the guideline for
98 contributing code to DataMapper.
99
100 <ol>
101 <li>
102 <p>Create a local working copy of the source code (we did this earlier.)</p>
103 {% highlight bash %}
104 # See above for the exact invocation
105 {% endhighlight %}
106 </li>
107
108 <li>
109 <p>Change to the newly created directory that contains the local working copy. (Substitute the directory if you created it with a different name, obviously.)</p>
110 {% highlight bash %}
111 cd dm
112 {% endhighlight %}
113 </li>
114
115 <li>
116 <p>Create a branch for your work. It is important that you do your work in a local branch, rather than master.</p>
117 {% highlight bash %}
118 git checkout -b new_feature
119 {% endhighlight %}
120 </li>
121
122 <li>
123 <p>Edit the code and test your changes. Then commit to your local working copy.</p>
124 {% highlight bash %}
125 git add .
126 git commit
127 {% endhighlight %}
128 </li>
129
130 <li>
131 <p>When you are ready to send your local changes back to the DataMapper repository, you first need to ensure that your local copy is up-to-date. First, ensure you have committed your local changes. Then switch from your topic branch to the master branch.</p>
132 {% highlight bash %}
133 git checkout master
134 {% endhighlight %}
135 </li>
136
137 <li>
138 <p>Update your local copy with changes from the DataMapper repository</p>
139 {% highlight bash %}
140 git pull origin master --rebase
141 {% endhighlight %}
142 </li>
143
144 <li>
145 <p>Switch back to your topic branch and integrate any new changes. The git rebase command will save your changes away, update the topic branch, and then reapply them.</p>
146 {% highlight bash %}
147 git checkout new_feature
148 git rebase master
149 {% endhighlight %}
150 <p>Warning! If you have shared the topic branch publicly, you must use</p>
151
152 {% highlight bash %}
153 git merge master
154 {% endhighlight %}
155 <p>Rebase causes the commit layout to change and will confuse anyone
156 you&#8217;ve shared this branch with.</p> </li>
157
158 <li>
159 <p>If there are conflicts applying your changes during the git rebase command, fix them and use the following to finish applying them</p>
160 {% highlight bash %}
161 git rebase --continue
162 {% endhighlight %}
163 </li>
164
165 <li>
166 <p>Now, switch back to the master branch and merge your changes from the topic branch</p>
167 {% highlight bash %}
168 git checkout master
169 git merge new_feature
170 {% endhighlight %}
171 </li>
172
173 <li>
174 <p>You might want to check that your commits ended up as you intended. To do so, you can have a look at the log</p>
175 {% highlight bash %}
176 git log
177 {% endhighlight %}
178 </li>
179
180 <li>
181 <p>Get your changes in the main repository. If you have commit rights, you can just use the git push command. Otherwise, see the section below for information on creating a set of patches to send.</p>
182 {% highlight bash %}
183 git push origin master
184 {% endhighlight %}
185 </li>
186
187 <li>
188 <p>At this point, you can delete the branch if you like.</p>
189 {% highlight bash %}
190 git branch -d new_feature
191 {% endhighlight %}
192 </li>
193 </ol>
194
195 Patches: git-format-patch
196 -------------------------
197
198 If you are a new committer (or want to create a patch instead of directly
199 pushing the code for some other reason) you should create a patch file for your
200 commits. The patch file should be then attached to a ticket on Lighthouse. You
201 can also send the patch to the mailing list but please use the ticket tracker if
202 at all possible. Either way, the patch file(s) should be created using Git.
203
204 First, make your changes as detailed below and then use the git format-patch
205 command to create the patch files. Usually using the command is as simple as
206 specifying the commits you want to create patches for, and that is done in one
207 of two ways: by giving a range of commits or a starting point.
208
209 For our purposes, the simplest way to create a patch is to begin at the end of
210 step 8 above (after you have rebased your branch) and then, instead of
211 merging:
212
213 {% highlight bash %}
214 git format-patch master..
215 {% endhighlight %}
216
217 This will create a separate patch file for each commit in your working branch
218 that is not in master, named `[number]-[first line of commit message].patch`. You
219 can then attach these to a ticket (or e-mail them).
220
221 You can also inspect your changes using `git log master..` or `git diff master..`
222 to ensure that the patches will be generated correctly if you are uncertain.
Something went wrong with that request. Please try again.