1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 2018. |
---|
4 | .. COMMENT: RTEMS Foundation, The RTEMS Documentation Project |
---|
5 | |
---|
6 | |
---|
7 | Software Development (Git Writers) |
---|
8 | ********************************** |
---|
9 | |
---|
10 | .. COMMENT: TBD - Convert https://devel.rtems.org/wiki/Developer/Git/Committers |
---|
11 | .. COMMENT: TBD - and insert here. |
---|
12 | |
---|
13 | .. COMMENT: TBD - Some guidelines for anyone who wishes to contribute to |
---|
14 | .. COMMENT: TBD - rtems... Patches? Pull Requests?... |
---|
15 | |
---|
16 | The preferred workflow for making changes to RTEMS is to push patches to a |
---|
17 | committer's personal repository in public view and then merge changes from |
---|
18 | there. For working on enhancements or bug fixes committers are encouraged to |
---|
19 | push to branches on their personal repositories and to merge into the main |
---|
20 | RTEMS repository from their personal repository. Personal branches should |
---|
21 | not be pushed to the RTEMS repository. |
---|
22 | |
---|
23 | SSH Access |
---|
24 | ---------- |
---|
25 | |
---|
26 | Currently all committer's should have an ssh account on the main git server, |
---|
27 | dispatch.rtems.org. If you have been granted commit access and do have an |
---|
28 | account on dispatch.rtems.org one should be requested on the devel@ list. |
---|
29 | SSH access for git uses key logins instead of passwords. The key should be at |
---|
30 | least 1024 bits in length. |
---|
31 | |
---|
32 | The public repositories can by cloned with |
---|
33 | |
---|
34 | .. code-block:: shell |
---|
35 | |
---|
36 | git clone ssh://user@dispatch.rtems.org/data/git/rtems.git |
---|
37 | |
---|
38 | Or replace `rtems.git` with another repo to clone another one. |
---|
39 | |
---|
40 | Personal Repository |
---|
41 | ------------------- |
---|
42 | Personal repositories keep the clutter away from the master repository. A |
---|
43 | user with a personal repository can make commits, create and delete branches, |
---|
44 | plus more without interfering with the master repository. Commits to the |
---|
45 | master repository generate email to the vc@ list and development type commits |
---|
46 | by a developer would only add noise and lessen the effectiveness of the commit |
---|
47 | list |
---|
48 | |
---|
49 | A committer should maintain a personal clone of the RTEMS repository through |
---|
50 | which all changes merged into the RTEMS head are sent. The personal repository |
---|
51 | is also a good place for committers to push branches that contain works in |
---|
52 | progress. The following instructions show how to setup a personal repositor |
---|
53 | that by default causes commits to go to your private local repository and |
---|
54 | pushes to go to your publicly visible personal repository. The RTEMS head is |
---|
55 | configured as a remote repository named 'upstream' to which you can push |
---|
56 | changes that have been approved for merging into RTEMS. |
---|
57 | |
---|
58 | Branches aren't automatically pushed until you tell git to do the initial push |
---|
59 | after which the branch is pushed automatically. In order to keep code private |
---|
60 | just put it on a branch in your local clone and do not push the branch. |
---|
61 | |
---|
62 | Create a personal repository |
---|
63 | ---------------------------- |
---|
64 | |
---|
65 | Set up the server side repository. In the following substitute user with your |
---|
66 | username. |
---|
67 | |
---|
68 | .. code-block:: shell |
---|
69 | |
---|
70 | # ssh git.rtems.org |
---|
71 | [user@git ~]$ ln -s /data/git/user git |
---|
72 | [user@git ~]$ ls -l |
---|
73 | lrwxrwxrwx 1 user rtems 16 Feb 1 11:52 git -> /data/git/user |
---|
74 | [user@git ~]$ cd git |
---|
75 | [user@git git]$ git clone --mirror /data/git/rtems.git |
---|
76 | |
---|
77 | Provide a description for the repository, for example "Clone of master |
---|
78 | repository." |
---|
79 | |
---|
80 | .. code-block:: shell |
---|
81 | |
---|
82 | [user@git git]$ echo "Clone of master repository." > rtems.git/description |
---|
83 | [user@git git]$ logout |
---|
84 | |
---|
85 | Clone the repository on your local machine |
---|
86 | |
---|
87 | .. code-block:: shell |
---|
88 | |
---|
89 | # git clone ssh://user@dispatch.rtems.org/home/user/git/rtems.git |
---|
90 | # cd rtems |
---|
91 | |
---|
92 | Add the RTEMS repository as a remote repository and get the remote tags |
---|
93 | and branches |
---|
94 | |
---|
95 | .. code-block:: shell |
---|
96 | |
---|
97 | # git remote add upstream ssh://user@dispatch.rtems.org/data/git/rtems.git |
---|
98 | # git fetch upstream |
---|
99 | |
---|
100 | After a little while you should be able to see your personal repo |
---|
101 | at https://git.rtems.org/@USER@/rtems.git/ and you can create other |
---|
102 | repositories in your git directory that will propagate |
---|
103 | to https://git.rtems.org/@USER@/ if you need. For example, `joel`'s personal |
---|
104 | repos appear at https://git.rtems.org/joel/. |
---|
105 | |
---|
106 | |
---|
107 | .. figure:: ../images/eng/Git-personalrepo.png |
---|
108 | :width: 50% |
---|
109 | :align: center |
---|
110 | :alt: Git Personal Repositories |
---|
111 | |
---|
112 | Check your setup |
---|
113 | ~~~~~~~~~~~~~~~~ |
---|
114 | |
---|
115 | .. code-block:: shell |
---|
116 | |
---|
117 | git remote show origin |
---|
118 | |
---|
119 | Should print something similar to |
---|
120 | |
---|
121 | .. code-block:: shell |
---|
122 | |
---|
123 | * remote origin |
---|
124 | Fetch URL: ssh://user@dispatch.rtems.org/home/user/git/rtems.git |
---|
125 | Push URL: ssh://user@dispatch.rtems.org/home/user/git/rtems.git |
---|
126 | HEAD branch: master |
---|
127 | Remote branches: |
---|
128 | 4.10 tracked |
---|
129 | 4.8 tracked |
---|
130 | 4.9 tracked |
---|
131 | master tracked |
---|
132 | Local branch configured for 'git pull': |
---|
133 | master merges with remote master |
---|
134 | Local ref configured for 'git push': |
---|
135 | master pushes to master (up to date) |
---|
136 | |
---|
137 | Push commits to personal repo master from local master |
---|
138 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
139 | |
---|
140 | .. code-block:: shell |
---|
141 | |
---|
142 | # git push |
---|
143 | |
---|
144 | Push a branch onto personal repo |
---|
145 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
146 | |
---|
147 | .. code-block:: shell |
---|
148 | |
---|
149 | # git push origin branchname |
---|
150 | |
---|
151 | Update from upstream master (RTEMS head) |
---|
152 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
---|
153 | |
---|
154 | When you have committed changes on a branch that is private (hasn't been |
---|
155 | pushed to your personal repo) then you can use rebase to obtain a linear |
---|
156 | history and avoid merge commit messages. |
---|
157 | |
---|
158 | .. code-block:: shell |
---|
159 | |
---|
160 | # git checkout new_features |
---|
161 | # git pull --rebase upstream master |
---|
162 | |
---|
163 | If you cannot do a fast-forward merge then you could use the ``--no-commit`` |
---|
164 | flag to prevent merge from issuing an automatic merge commit message. |
---|
165 | |
---|
166 | When you have committed changes on a branch that is public/shared with another |
---|
167 | developer you should not rebase that branch. |
---|
168 | |
---|
169 | GIT Push Configuration |
---|
170 | ---------------------- |
---|
171 | |
---|
172 | People with write access to the main repository should make sure that they |
---|
173 | push the right branch with the git push command. The above setup ensures |
---|
174 | that git push will not touch the main repository, which is identified as |
---|
175 | upstream, unless you specify the upstream (by ``git push upstream master``). |
---|
176 | |
---|
177 | Lets suppose we have a test branch intended for integration into the master |
---|
178 | branch of the main repository. |
---|
179 | |
---|
180 | .. code-block:: shell |
---|
181 | |
---|
182 | # git branch |
---|
183 | master |
---|
184 | * test |
---|
185 | |
---|
186 | There are two options for pushing with the branch. First, |
---|
187 | |
---|
188 | .. code-block:: shell |
---|
189 | |
---|
190 | # git push origin test |
---|
191 | |
---|
192 | Will push the test branch to the personal repository. To delete the remote |
---|
193 | branch |
---|
194 | |
---|
195 | .. code-block:: shell |
---|
196 | |
---|
197 | # git push origin :test |
---|
198 | |
---|
199 | You'll still need to delete your local branch if you are done with it. |
---|
200 | |
---|
201 | If you are going to work exclusively with one branch for a while, you might |
---|
202 | want to configure git to automatically push that branch when you use git push. |
---|
203 | By default git push will use the local master branch, but you can use the |
---|
204 | `test` branch as the source of your changes: |
---|
205 | |
---|
206 | .. code-block:: shell |
---|
207 | |
---|
208 | # git config remote.origin.push test:master |
---|
209 | |
---|
210 | Now git push will merge into your master branch on your personal repository. |
---|
211 | You can also setup a remote branch: |
---|
212 | |
---|
213 | .. code-block:: shell |
---|
214 | |
---|
215 | # git config remote.origin.push test:test |
---|
216 | |
---|
217 | You can see what branch is configured for pushing with |
---|
218 | |
---|
219 | .. code-block:: shell |
---|
220 | |
---|
221 | # git remote show origin |
---|
222 | |
---|
223 | And reset to the default |
---|
224 | |
---|
225 | .. code-block:: shell |
---|
226 | |
---|
227 | # git config remote.origin.push master |
---|
228 | |
---|
229 | Pull a Developer's Repo |
---|
230 | ----------------------- |
---|
231 | |
---|
232 | The procedures for creating personal repositories ensure that every developer |
---|
233 | can post branches that anyone else can review. To pull a developer's personal |
---|
234 | repository into your local RTEMS git clone, just add a new remote repo: |
---|
235 | |
---|
236 | .. code-block:: shell |
---|
237 | |
---|
238 | # git remote add devname git://dispatch.rtems.org/devname/rtems.git |
---|
239 | # git fetch devname |
---|
240 | # git remote show devname |
---|
241 | # git branch -a |
---|
242 | |
---|
243 | Replace devname with the developer's user name on git, which you can see by |
---|
244 | accessing https://git.rtems.org. Now you can switch to the branches |
---|
245 | for this developer. |
---|
246 | |
---|
247 | Use a tracking branch if the developer's branch is changing: |
---|
248 | |
---|
249 | .. code-block:: shell |
---|
250 | |
---|
251 | # git branch --track new_feature devname/new_feature |
---|
252 | |
---|
253 | Committing |
---|
254 | ---------- |
---|
255 | |
---|
256 | Ticket Updates |
---|
257 | ~~~~~~~~~~~~~~ |
---|
258 | |
---|
259 | Our trac instance supports updating a related ticket with the commit message. |
---|
260 | |
---|
261 | Any references to a ticket for example #1234 will insert the message into |
---|
262 | he ticket as an 'update'. No command is required. |
---|
263 | |
---|
264 | Closing a ticket can be done by prefixing the ticket number with any of the |
---|
265 | following commands: |
---|
266 | |
---|
267 | ``close``, ``closed``, ``closes``, ``fix``, ``fixed``, or ``fixes`` |
---|
268 | |
---|
269 | For example: |
---|
270 | |
---|
271 | ``closes #1234`` |
---|
272 | |
---|
273 | ``This is a random update it closes #1234 and updates #5678`` |
---|
274 | |
---|
275 | Commands |
---|
276 | ~~~~~~~~ |
---|
277 | |
---|
278 | When merging someone's work, whether your own or otherwise, we have some |
---|
279 | suggested procedures to follow. |
---|
280 | |
---|
281 | * Never work in the master branch. Checkout a new branch and apply |
---|
282 | patches/commits to it. |
---|
283 | * Before pushing upstream: |
---|
284 | - Update master by fetching from the server |
---|
285 | - Rebase the working branch against the updated master |
---|
286 | - Push the working branch to the server master |
---|
287 | |
---|
288 | The basic workflow looks like |
---|
289 | |
---|
290 | .. code-block:: shell |
---|
291 | |
---|
292 | # git checkout -b somebranch upstream/master |
---|
293 | # patch .. git add/rm/etc |
---|
294 | # git commit ... |
---|
295 | # git pull --rebase upstream master |
---|
296 | # git push upstream somebranch:master |
---|
297 | |
---|
298 | If someone pushed since you updated the server rejects your push until you |
---|
299 | are up to date. |
---|
300 | |
---|
301 | For example a workflow where you will commit a series of patches from |
---|
302 | ``../patches/am/`` directory: |
---|
303 | |
---|
304 | .. code-block:: shell |
---|
305 | |
---|
306 | # git checkout -b am |
---|
307 | # git am ../patches/am* |
---|
308 | # git pull --rebase upstream master |
---|
309 | # git push upstream am:master |
---|
310 | # git checkout master |
---|
311 | # git pull upstream master |
---|
312 | # git log |
---|
313 | # git branch -d am |
---|
314 | # git push |
---|
315 | |
---|
316 | The git log stage will show your newly pushed patches if everything worked |
---|
317 | properly, and you can delete the am branch created. The git push at the end |
---|
318 | will push the changes up to your personal repository. |
---|
319 | |
---|
320 | Another way to do this which pushes directly to the upstream is shown here |
---|
321 | in an example which simply (and quickly) applies a patch to the branch: |
---|
322 | |
---|
323 | .. code-block:: shell |
---|
324 | |
---|
325 | git checkout -b rtems4.10 --track remotes/upstream/4.10 |
---|
326 | cat /tmp/sp.diff | patch |
---|
327 | vi sparc.t |
---|
328 | git add sparc.t |
---|
329 | git commit -m "sparc.t: Correct for V8/V9" |
---|
330 | git push upstream rtems4.10:4.10 |
---|
331 | git checkout master |
---|
332 | git log |
---|
333 | git branch -d rtems4.10 |
---|
334 | |
---|
335 | Pushing Multiple Commits |
---|
336 | ------------------------ |
---|
337 | |
---|
338 | A push with more than one commit results in Trac missing them. Please use the |
---|
339 | following script to push a single commit at a time: |
---|
340 | |
---|
341 | .. code-block:: shell |
---|
342 | |
---|
343 | #! /bin/sh |
---|
344 | commits=$(git log --format='%h' origin/master..HEAD | tail -r) |
---|
345 | for c in $commits |
---|
346 | do |
---|
347 | cmd=$(echo $c | sed 's%\(.*\)%git push origin \1:master%') |
---|
348 | echo $cmd |
---|
349 | $cmd |
---|
350 | done |
---|
351 | |
---|
352 | Ooops! |
---|
353 | ------ |
---|
354 | |
---|
355 | So you pushed something upstream and broke the repository. First things first: |
---|
356 | stop what you're doing and notify devel@... so that (1) you can get help and |
---|
357 | (2) no one pulls from the broken repo. For an extended outage also notify |
---|
358 | users@.... Now, breathe easy and let's figure out what happened. One thing |
---|
359 | that might work is to just `undo the push |
---|
360 | <https://stackoverflow.com/questions/1270514/undoing-a-git-push>`_. To get an |
---|
361 | idea of what you did, run ``git reflog``, which might be useful for getting |
---|
362 | assistance in undoing whatever badness was done. |
---|