| blob | 9a8cb0c7a74d8a908c28e0a913ddd7cafe411462 |
3 <html>
4 <head>
10 </head>
11 <body>
13 <p>
14 <em>Translations of this page are also available in the following languages:</em> <a href="geda-scm.ru.html" class="wikilink1" title="geda-scm.ru.html">Русский</a>.
15 </p>
20 <p>
21 gEDA uses <strong>git</strong> for source code management. git is a distributed version control system, where every user has his or her own full copy of the revision history.
22 </p>
23 <ul>
25 </li>
27 </li>
28 </ul>
30 <p>
31 Some nice tutorials:
32 </p>
33 <ul>
35 </li>
37 </li>
38 <li class="level1"><div class="li"> Git - The Simple Guide -- very concise and condensed cheat sheet style tutorial</div>
39 </li>
40 </ul>
42 </div>
47 <p>
48 To clone the geda-gaf.git repository (or any repository hosted at git.geda-project.org) using anonymous git access:
49 </p>
52 <p>
53 or
54 </p>
57 <p>
58 For different repositories hosted at git.geda-project.org, just substitute the last part of the above URL.
59 </p>
61 <p>
62 There is a cgit interface to the repositories of the various projects. Just point a www browser to http://git.geda-project.org/ .
63 </p>
65 </div>
70 <p>
71 Branches are a major feature of git. The geda project uses feature branches to test non-trivial changes. Once they are assessed as useful, the changes a branch represents gets merged into the main head. You can try and test a feature branch even if you don't have write access to the git repository of geda-project, yet.
72 </p>
74 </div>
79 <p>
80 To list all branches of a project available on the geda-project server cd to your local copy of the project and emit this git command:
81 </p>
84 </div>
89 <p>
90 This will create a branch with the name <code><local name></code> in your local repository, which tracks the <code><remote name></code>'d branch.
91 </p>
94 <p>
95 Go ahead and build the application from the branch as described by the <a href="geda-gaf_building_git_version.html" class="wikilink1" title="geda-gaf_building_git_version.html">build instructions</a>. By default the command <code>make install</code> will copy the binaries to <code>/usr/local/*</code>. That way, it will not interfere with an install done by your linux distribution. You may use full paths, symbolic links or aliases to pick which version to use.
96 </p>
98 </div>
103 <p>
104 Generally, there will be a launchpad bug associated with the feature of the branch. Please report your experience with the branch there. Your input will influence whether or not the feature will make into mainstream. There is a group of users and developers who keep an eye on changes to bug reports. They will get noticed by email.
105 </p>
107 <p>
108 For additional visibility you may report your experience on the mailing list <a href="geda-mailinglists.html" class="wikilink1" title="geda-mailinglists.html">geda-user</a>. It may even spark a discussion. As with all forms of general online discussion, the note may get archived and gradually be forgotten without any action taken.
109 </p>
111 </div>
116 <p>
117 The simplest possible way includes all changes since the local repository was syncronized with the repository at geda-project.org:
118 </p>
121 <p>
122 A more complicated way with more control on what the patch contains:
123 </p>
126 $ git commit # create a commit
129 <p>
130 This will output a filename which contains the patch. Be sure to look at the documentation for format-patch for more information. This file can be e-mailed to developers who have write access and can be applied using git apply.
131 </p>
133 </div>
135 <h2 id="accesstherepositorywithwritepermission">Access the repository with write permission</h2>
138 <p>
139 For developer git access, you should write DJ Delorie or Traumflug an email with your SSH public key and your preferred user name. They'll install this key on the server, then. Having done so, the git URL to push to is (note the <em>:65</em>):
140 </p>
143 <p>
144 Note: If you're having trouble pushing commits upstream, make sure you're using git 1.5 or newer.
145 </p>
147 <p>
148 Accordingly, to grab a repository copy with write privileges you'd do this:
149 </p>
152 <p>
153 If you have a read-only clone already you can change it to one with write access:
154 </p>
158 <p>
159 Having this done, your local clone works just as before, just a <code>git push origin <branch></code> succeeds.
160 </p>
162 </div>
167 <p>
168 You can use a separate key for accessing the gEDA git access. This has no further advantage other than having a unique key. In this case you may also need to add a line to your ~/.ssh/config file to specify this alternate key:
169 </p>
171 Port 65
172 IdentityFile ~/.ssh/gedaproject_dsa</pre>
174 <p>
175 Note, the file you refer to here is the private key. By contrast, the file you send for the server side is the corresponding public key.
176 </p>
178 </div>
183 </div>
188 <p>
189 You should make sure that your username & e-mail address are set in your git configuration file.
190 </p>
192 $ git config --global user.email you@yourdomain.example.com</pre>
194 </div>
199 <p>
200 If you apply a patch from someone else (e.g. from a launchpad patch record) there are a few things to consider.
201 Git stores two different names and e-mail addresses for a given commit: the "author" of the patch, and the "committer" of the patch, so these details must be set correctly when making the commit.
202 </p>
204 <p>
205 First of all, check a few things:
206 </p>
207 <ul>
209 </li>
210 <li class="level1"><div class="li"> The author of the patch is happy for it to be committed (and wasn't still working on it)</div>
211 </li>
212 <li class="level1"><div class="li"> That the you're happy with the patch, and taking responsibility for committing those changes.</div>
213 </li>
214 </ul>
216 <p>
217 For simplicity, start from an unmodified up-to date tree (git status shows no changes).
218 </p>
220 <p>
221 Apply the patch as usual (as an example):
222 </p>
225 <p>
226 You can also use the git apply command:
227 </p>
230 <p>
231 If the patch needs any minor editing before it is committed (eg. white-space changes), please inform the author this was done.
232 They may have other work based on their patch and will want to know if there were changes to the applied version.
233 </p>
234 <div class="noteclassic">This is easy to miss accidentally if your editor introduces tabs. Please avoid letting it do so!
235 </div>
236 <p>
237 For every file changed, added or removed, you need to inform git before it will commit the changes. To see the modified files, run:
238 </p>
241 <p>
242 For speed, the command:
243 </p>
246 <p>
247 will update all files which git tracks, including any files which were deleted.
248 </p>
250 <p>
251 For adding any new files the patch introduced, use the command
252 </p>
255 <p>
256 Note: git add also takes wild-cards.
257 </p>
259 <p>
260 Commit the patch, making sure that the Author's name and e-mail address are specified:
261 </p>
262 <pre class="code">$ git commit --author "Author's Name Comes Here <author@example.com>"</pre>
264 <p>
265 As an alternative, you can set the GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL environment variables before issuing the normal commit command
266 </p>
268 </div>
273 <p>
274 The commit message format is as follows: a *strictly* one-line summary of the patch, followed by a blank line, followed by a long description. If you can fit the whole description of the patch on one line, that's fine; don't bother with the long description.
275 </p>
277 <p>
278 The one-line summary is used for generating e-mail subject lines, and for the gitk & gitweb log displays. Having a good one-line summary is really useful, because it means those tools can be used to quickly find a commit of interest.
279 </p>
281 <p>
282 <strong>Do not</strong> put a list of files changed into commit messages. This information can be trivially obtained using the git tools.
283 </p>
285 <p>
286 Example:
287 </p>
290 This abstracts a GList with API for write access. Its main use is in list
292 Read only access to the underlying GList is provided by an accessor,
293 currenly implemented as a macro.</pre>
295 </div>
300 <p>
301 For those who are are not merging changes back into the central git repository you can run:
302 </p>
305 <p>
306 However, for those of you who are going to be pushing your changes back into the central git repository, using git pull will clutter up the history with merge messages ("Merge branch 'master'"). To avoid this you should run:
307 </p>
309 $ git rebase origin</pre>
311 </div>
317 <p>
318 This command will find all changed files that git knows about (added with git-add) and prompt you for a commit message. Be sure to follow the above commit message convention if you plan on pushing your changes to the central repository.
319 </p>
321 <p>
322 If you want to commit files in the current directory or want to explicitly commit only certain files, do not specify the -a flag and/or specify the individual filenames on the command line like:
323 </p>
326 </div>
332 <p>
333 Note this will discard any changes to any files that are being tracked by git.
334 </p>
336 <p>
337 If you want to just discard edits in a single file, just run:
338 </p>
341 <p>
342 If you want to discard all edits from the current directory and downward recursively, just run:
343 </p>
346 </div>
351 $ git commit --amend filename1..filenameN</pre>
353 <p>
354 This will pickup any changes you made and recommit them again with the previous commit message.
355 </p>
357 </div>
362 <p>
363 If you have write permission to the git repository of the gEDA project, you can create personalized branches for your patches. This is recommend to facilitate tests, review and finally application of the patches to the master branch of the application. For this purpose a personalized name space is available in the git repositories. The prefix of this name space is <code>home/<user_name>/</code>, where <code><user_name></code> is your user name.
364 </p>
366 <p>
367 First create the branch locally and simultaneously switch to it as the current branch:
368 </p>
371 <p>
372 Make some changes. Stage the changes and issue a commit:
373 </p>
377 <p>
379 </p>
381 <p>
382 To publish the changed branch to the remote repository do:
383 </p>
386 <p>
387 The first push to a branch creates it on the remote server.
388 For a little more convenience, you can advise git to always push to the current branch:
389 </p>
392 <p>
393 Skip the option <code>--global</code> if you want this to be active only in this particular git project. With this directive the command above reduces to a mere
394 </p>
396 </pre>
398 </div>
403 <p>
404 In case you'd rather not have your branch sitting indefinitely in the remote repository, you can issue a delete directive. To delete the branch on the server do:
405 </p>
406 <pre class="code"> $ git push origin --delete home/<user_name>/<name_of_the_branch></pre>
408 <p>
409 To delete the branch on the local repository, too:
410 </p>
412 </pre>
414 </div>
416 <h2 id="fetchadevelopmentbranchfromotherpeople">Fetch a development branch from other people</h2>
419 <p>
420 Beside the http://git.geda-project.org/ repository we have a mirror of that repository at http://repo.or.cz/w/geda-gaf.git. Some of the developers have forks of that repository with new feature branches.
421 </p>
423 <p>
424 If you like to test one of the feature branches you have to fetch it from their repository.
425 The easiest way to get a branch is to use the fetch command.
426 </p>
429 <p>
432 </p>
433 <pre class="code"> $ git fetch git://repo.or.cz/geda-gaf/pcjc2.git cairo_experiment:peters_cairo_experiment</pre>
435 <p>
436 Now you can switch to the local copy of the branch <em>peters_cairo_experiment</em> and play with it.
437 </p>
439 <p>
440 It is also possible to add multiple remote forks into the local repository:
441 </p>
445 <p>
447 need to create local branches. With a tool like gitk it is now possible to keep
448 an eye on development in various feature branches on various forks:
449 </p>
452 <p>
454 </p>
456 $ git fetch peter-b
457 $ git remote add gareth8118 https://github.com/gareth8118/geda-gaf.git
458 $ git fetch gareth8118
459 $ git remote add bert https://github.com/bert/geda-gaf.git
460 $ git fetch bert
461 $ gitk --all</pre>
463 <p>
464 Now gitk can become quite filled up, but <strong>File</strong>-><strong>List references</strong> (<kbd>F2</kbd>) will open
465 a dialog for easier navigation.
466 </p>
468 <p>
469 Updating favourite remotes will then boil down to:
470 </p>
473 </div>
475 <h2 id="recoverfromareallymesseduplocalrepository">Recover from a really messed up local repository</h2>
478 <p>
479 First off, do not push any repository that you think is somehow messed up. Ask one of the experienced git people first.
480 </p>
482 <p>
483 Second, the command that will really save your bacon is git-reflog. Using it works something like this:
484 </p>
489 ...
492 <p>
493 The last command (git reset --hard ...) will rollback all your changes to the "checkout: moving to master". Remember: don't panic! Most things are fixable when using git.
494 </p>
496 </div>
497 </body>
498 </html>