docs/wiki/geda_scm.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en"
   4  lang="en" dir="ltr">
   5 <head>
   6   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   7   <title>geda:scm</title>
   8 <meta name="generator" content="DokuWiki Release rc2007-05-24" />
   9 <meta name="robots" content="noindex,nofollow" />
  10 <meta name="date" content="2007-07-04T19:34:57-0400" />
  11 <meta name="keywords" content="geda,scm" />
  12 <link rel="search" type="application/opensearchdescription+xml" href="http://geda.seul.org/wiki/lib/exe/opensearch.php" title="geda Wiki" />
  13 <link rel="start" href="http://geda.seul.org/wiki/" />
  14 <link rel="contents" href="http://geda.seul.org/wiki/geda:scm?do=index" title="Index" />
  15 <link rel="alternate" type="application/rss+xml" title="Recent Changes" href="http://geda.seul.org/wiki/feed.php" />
  16 <link rel="alternate" type="application/rss+xml" title="Current Namespace" href="http://geda.seul.org/wiki/feed.php?mode=list&ns=geda" />
  17 <link rel="alternate" type="text/html" title="Plain HTML" href="http://geda.seul.org/wiki/_export/xhtml/geda:scm" />
  18 <link rel="alternate" type="text/plain" title="Wiki Markup" href="http://geda.seul.org/wiki/_export/raw/geda:scm" />
  19 <link rel="stylesheet" media="all" type="text/css" href="lib/exe/css" />
  20 <link rel="stylesheet" media="screen" type="text/css" href="lib/exe/001css" />
  21 <link rel="stylesheet" media="print" type="text/css" href="lib/exe/002css" />
  22 </head>
  23 <body>
  24 <div class="dokuwiki export">
  25 <div class="toc">
  26 <div class="tocheader toctoggle" id="toc__header">Table of Contents</div>
  27 <div id="toc__inside">
  28
  29 <ul class="toc">
  30 <li class="level1"><div class="li"><span class="li"><a href="#geda_gaf_s_source_control_management" class="toc">gEDA/gaf&#039;s Source Control Management</a></span></div>
  31 <ul class="toc">
  32 <li class="level2"><div class="li"><span class="li"><a href="#installing_git_related_tools" class="toc">Installing git &amp; related tools</a></span></div>
  33 <ul class="toc">
  34 <li class="level3"><div class="li"><span class="li"><a href="#debian-based" class="toc">Debian-based</a></span></div></li>
  35 <li class="level3"><div class="li"><span class="li"><a href="#fedora_linux" class="toc">Fedora Linux</a></span></div></li>
  36 </ul>
  37 </li>
  38 <li class="level2"><div class="li"><span class="li"><a href="#learning_to_use_git" class="toc">Learning to use git</a></span></div></li>
  39 <li class="level2"><div class="li"><span class="li"><a href="#accessing_the_repository" class="toc">Accessing the repository</a></span></div></li>
  40 <li class="level2"><div class="li"><span class="li"><a href="#making_and_committing_changes" class="toc">Making and committing changes</a></span></div>
  41 <ul class="toc">
  42 <li class="level3"><div class="li"><span class="li"><a href="#setting_up_user_information" class="toc">Setting up user information</a></span></div></li>
  43 <li class="level3"><div class="li"><span class="li"><a href="#committing_patches_from_other_contributors" class="toc">Committing patches from other contributors</a></span></div></li>
  44 <li class="level3"><div class="li"><span class="li"><a href="#writing_good_commit_messages" class="toc">Writing good commit messages</a></span></div></li>
  45 <li class="level3"><div class="li"><span class="li"><a href="#push_is_destructive" class="toc">Push is Destructive</a></span></div></li>
  46 </ul>
  47 </li>
  48 <li class="level2"><div class="li"><span class="li"><a href="#how_do_i" class="toc">How Do I ... ?</a></span></div>
  49 <ul class="toc">
  50 <li class="level3"><div class="li"><span class="li"><a href="#get_a_copy_of_geda_gaf_git_repository" class="toc">... get a copy of gEDA/gaf git repository?</a></span></div></li>
  51 <li class="level3"><div class="li"><span class="li"><a href="#keep_my_local_copy_current" class="toc">... keep my local copy current?</a></span></div></li>
  52 <li class="level3"><div class="li"><span class="li"><a href="#commit_my_changes_to_the_local_git_repository" class="toc">... commit my changes to the local git repository?</a></span></div></li>
  53 <li class="level3"><div class="li"><span class="li"><a href="#undo_any_uncommitted_local_changes" class="toc">... undo any uncommitted local changes?</a></span></div></li>
  54 <li class="level3"><div class="li"><span class="li"><a href="#fix_change_my_last_commit" class="toc">... fix/change my last commit?</a></span></div></li></ul>
  55 </li></ul>
  56 </li></ul>
  57 </div>
  58 </div>
  59
  60
  61
  62 <h1><a name="geda_gaf_s_source_control_management" id="geda_gaf_s_source_control_management">gEDA/gaf&#039;s Source Control Management</a></h1>
  63 <div class="level1">
  64
  65 <p>
  66  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.
  67 </p>
  68 <ul>
  69 <li class="level1"><div class="li"> <a href="http://git.or.cz/" class="urlextern" title="http://git.or.cz/"  rel="nofollow">Official git website</a></div>
  70 </li>
  71 <li class="level1"><div class="li"> <a href="http://www.kernel.org/pub/software/scm/git/docs/" class="urlextern" title="http://www.kernel.org/pub/software/scm/git/docs/"  rel="nofollow">git documentation online</a></div>
  72 </li>
  73 <li class="level1"><div class="li"> <a href="http://en.wikipedia.org/wiki/Git_(software)" class="urlextern" title="http://en.wikipedia.org/wiki/Git_(software)"  rel="nofollow">git Wikipedia page</a></div>
  74 </li>
  75 </ul>
  76
  77 <p>
  78  The web interface to the gEDA git repository is at <a href="http://git.gpleda.org/" class="urlextern" title="http://git.gpleda.org/"  rel="nofollow">http://git.gpleda.org/</a>.
  79 </p>
  80
  81 </div>
  82 <!-- SECTION "gEDA/gaf's Source Control Management" [1-493] -->
  83 <h2><a name="installing_git_related_tools" id="installing_git_related_tools">Installing git &amp; related tools</a></h2>
  84 <div class="level2">
  85
  86 <p>
  87  The core git tools are of course required for using the repository, and the documentation is always useful.  However, other tools are often helpful for working with git:
  88 </p>
  89 <ul>
  90 <li class="level1"><div class="li"> gitk, a visual history repository browser</div>
  91 </li>
  92 <li class="level1"><div class="li"> <a href="http://git.or.cz/cogito/" class="urlextern" title="http://git.or.cz/cogito/"  rel="nofollow">Cogito</a>, a more user-friendly front-end to git</div>
  93 </li>
  94 <li class="level1"><div class="li"> <a href="http://www.procode.org/stgit/" class="urlextern" title="http://www.procode.org/stgit/"  rel="nofollow">Stacked Git</a>, for working with patchsets</div>
  95 </li>
  96 </ul>
  97
  98 <p>
  99  Make sure that you install at least version 1.5.x of git if you are planning on pushing changes to the central git repository.
 100 </p>
 101
 102 </div>
 103 <!-- SECTION "Installing git & related tools" [494-1042] -->
 104 <h3><a name="debian-based" id="debian-based">Debian-based</a></h3>
 105 <div class="level3">
 106 <pre class="code">apt-get install git-core git-doc gitk cogito stgit</pre>
 107
 108 <p>
 109  you may also want:
 110 </p>
 111 <pre class="code">apt-get install git-email git-completion</pre>
 112
 113 <p>
 114  Note, as of 2007/06/25, Debian stable (etch) and Debian testing (lenny) have git version 1.4.x.  Debian unstable (sid) has 1.5.2.2.
 115 </p>
 116
 117 </div>
 118 <!-- SECTION "Debian-based" [1043-1317] -->
 119 <h3><a name="fedora_linux" id="fedora_linux">Fedora Linux</a></h3>
 120 <div class="level3">
 121 <pre class="code">yum install git cogito stgit</pre>
 122
 123 </div>
 124 <!-- SECTION "Fedora Linux" [1318-1375] -->
 125 <h2><a name="learning_to_use_git" id="learning_to_use_git">Learning to use git</a></h2>
 126 <div class="level2">
 127
 128 <p>
 129  The toplevel documentation for git can be found at:
 130 </p>
 131
 132 <p>
 133 <a href="http://www.kernel.org/pub/software/scm/git/docs/" class="urlextern" title="http://www.kernel.org/pub/software/scm/git/docs/"  rel="nofollow">Official git docs</a>
 134 </p>
 135
 136 <p>
 137 The user’s manual for git can be found at:
 138 </p>
 139
 140 <p>
 141 <a href="http://www.kernel.org/pub/software/scm/git/docs/user-manual.html" class="urlextern" title="http://www.kernel.org/pub/software/scm/git/docs/user-manual.html"  rel="nofollow">git user manual</a>
 142 </p>
 143
 144 <p>
 145 A current tutorial can be found at:
 146 </p>
 147
 148 <p>
 149 <a href="http://www.kernel.org/pub/software/scm/git/docs/core-tutorial.html" class="urlextern" title="http://www.kernel.org/pub/software/scm/git/docs/core-tutorial.html"  rel="nofollow">git core tutorial</a>
 150 </p>
 151
 152 <p>
 153 Other nice tutorials/webpages:
 154 </p>
 155
 156 <p>
 157 <a href="http://wiki.sourcemage.org/Git_Guide" class="urlextern" title="http://wiki.sourcemage.org/Git_Guide"  rel="nofollow">Git Guide</a><br/>
 158  <a href="http://wiki.sourcemage.org/Cogito_Guide" class="urlextern" title="http://wiki.sourcemage.org/Cogito_Guide"  rel="nofollow">Cogito Guide</a><br/>
 159  <a href="http://git.or.cz/course/index.html" class="urlextern" title="http://git.or.cz/course/index.html"  rel="nofollow">git Crash Courses</a><br/>
 160  <a href="http://git.or.cz/course/cvs.html" class="urlextern" title="http://git.or.cz/course/cvs.html"  rel="nofollow">Cogito for CVS Users</a><br/>
 161  <a href="http://www.kernel.org/pub/software/scm/git/docs/tutorial.html" class="urlextern" title="http://www.kernel.org/pub/software/scm/git/docs/tutorial.html"  rel="nofollow">Git for Everyone</a><br/>
 162
 163 </p>
 164
 165 <p>
 166 Keep in mind that some of these tutorials are a little dated and may not cover current git syntax.
 167 </p>
 168
 169 </div>
 170 <!-- SECTION "Learning to use git" [1376-2242] -->
 171 <h2><a name="accessing_the_repository" id="accessing_the_repository">Accessing the repository</a></h2>
 172 <div class="level2">
 173
 174 <p>
 175  To clone the gaf.git repository using anonymous git access:
 176 </p>
 177 <pre class="code">git clone git://git.gpleda.org/gaf.git</pre>
 178
 179 <p>
 180  For developer git access, you should contact Ales Hvezda to get an <acronym title="Secure Shell">SSH</acronym> public key installed and an account; having done so, the git <acronym title="Uniform Resource Locator">URL</acronym> to push to is:
 181 </p>
 182 <pre class="code">git clone ssh://&lt;username&gt;@git.gpleda.org/home/git/gaf.git</pre>
 183
 184 <p>
 185  If you have ssh access you will also need to edit your ~/.ssh/config file (create it if it doesn’t exist) and put the following text into it:
 186 </p>
 187 <pre class="code">Host git.gpleda.org
 188 Port 5022</pre>
 189
 190 <p>
 191  Finally, it is possible to access the repository using <acronym title="Concurrent Versions System">CVS</acronym>, as there is a git-cvsserver running.  This is read-only access.
 192 </p>
 193 <pre class="code"> export CVSROOT=:pserver:anonymous@git.gpleda.org/home/git/gaf.git
 194  cvs co master    </pre>
 195
 196 <p>
 197  You can only checkout exported heads (for example: master).
 198 </p>
 199
 200 </div>
 201 <!-- SECTION "Accessing the repository" [2243-3053] -->
 202 <h2><a name="making_and_committing_changes" id="making_and_committing_changes">Making and committing changes</a></h2>
 203 <div class="level2">
 204
 205 </div>
 206 <!-- SECTION "Making and committing changes" [3054-3098] -->
 207 <h3><a name="setting_up_user_information" id="setting_up_user_information">Setting up user information</a></h3>
 208 <div class="level3">
 209
 210 <p>
 211  You should make sure that your username &amp; e-mail address are set in your git configuration file.
 212 </p>
 213 <pre class="code">$ git config --global user.name &quot;Your Name Comes Here&quot;
 214 $ git config --global user.email you@yourdomain.example.com</pre>
 215
 216 </div>
 217 <!-- SECTION "Setting up user information" [3099-3356] -->
 218 <h3><a name="committing_patches_from_other_contributors" id="committing_patches_from_other_contributors">Committing patches from other contributors</a></h3>
 219 <div class="level3">
 220
 221 <p>
 222  If you apply a patch from someone else (e.g. from a SourceForge patch record) there are a few things to consider. 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.
 223 </p>
 224
 225 <p>
 226 First of all, check a few things:
 227 </p>
 228 <ul>
 229 <li class="level1"><div class="li"> You have the latest version of the patch.</div>
 230 </li>
 231 <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>
 232 </li>
 233 <li class="level1"><div class="li"> That the you’re happy with the patch, and taking responsibility for committing those changes.</div>
 234 </li>
 235 </ul>
 236
 237 <p>
 238  For simplicity, start from an unmodified up-to date tree (git status shows no changes).
 239 </p>
 240
 241 <p>
 242 Apply the patch as usual (as an example):
 243 </p>
 244 <pre class="code">$ patch -p1 &lt; example_changes.patch</pre>
 245
 246 <p>
 247  If the patch needs any minor editing before it is committed (eg. white-space changes), please inform the author this was done. They may have other work based on their patch and will want to know if there were changes to the applied version.
 248 </p>
 249
 250 <p>
 251 Note: <em>This is easy to miss accidentally if your editor introduces tabs. Please avoid letting it do so!</em>
 252 </p>
 253
 254 <p>
 255 For every file changed, added or removed, you need to inform git before it will commit the changes. To see the modified files, run:
 256 </p>
 257 <pre class="code">$ git status</pre>
 258
 259 <p>
 260  For speed, the command:
 261 </p>
 262 <pre class="code">$ git add -u</pre>
 263
 264 <p>
 265  will update all files which git tracks, including any files which were deleted.
 266 </p>
 267
 268 <p>
 269 For adding any new files the patch introduced, use the command
 270 </p>
 271 <pre class="code">$ git add new_file.c</pre>
 272
 273 <p>
 274  Note: git add also takes wild-cards.
 275 </p>
 276
 277 <p>
 278 Commit the patch, making sure that the Author’s name and e-mail address are specified:
 279 </p>
 280 <pre class="code">$ git commit --author &quot;Author&#039;s Name Comes Here &lt;author@example.com&gt;&quot;</pre>
 281
 282 <p>
 283  As an alternative, you can set the GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL environment variables before issuing the normal commit command
 284 </p>
 285
 286 </div>
 287 <!-- SECTION "Committing patches from other contributors" [3357-5208] -->
 288 <h3><a name="writing_good_commit_messages" id="writing_good_commit_messages">Writing good commit messages</a></h3>
 289 <div class="level3">
 290
 291 <p>
 292  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.
 293 </p>
 294
 295 <p>
 296 The one-line summary is used for generating e-mail subject lines, and for the gitk &amp; 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.
 297 </p>
 298
 299 <p>
 300 <strong>Do not</strong> put a list of files changed into commit messages.  This information can be trivially obtained using the git tools.
 301 </p>
 302
 303 <p>
 304 Example:
 305 </p>
 306 <pre class="code">
 307 Added new GedaList class derived from GObject
 308
 309 This abstracts a GList with API for write access. Its main use is in list
 310 change notification, as it emits a &quot;changed&quot; g_signal when modified.
 311 Read only access to the underlying GList is provided by an accessor,
 312 currenly implemented as a macro.
 313 </pre>
 314
 315 </div>
 316 <!-- SECTION "Writing good commit messages" [5209-6190] -->
 317 <h3><a name="push_is_destructive" id="push_is_destructive">Push is Destructive</a></h3>
 318 <div class="level3">
 319
 320 <p>
 321  <strong>Warning: pushing changes to the remote repository is destructive</strong>
 322 </p>
 323
 324 <p>
 325 Unlike <acronym title="Concurrent Versions System">CVS</acronym>, it is not the committing of changes which changes the master repository, but pushing changes using cg-push or git-push.  You should always double- (or triple-) check that the commits you are about to push are actually meant for the main repository.
 326 </p>
 327
 328 </div>
 329 <!-- SECTION "Push is Destructive" [6191-6555] -->
 330 <h2><a name="how_do_i" id="how_do_i">How Do I ... ?</a></h2>
 331 <div class="level2">
 332
 333 <p>
 334  For a more information please checkout the <a href="http://wiki.sourcemage.org/Git_Guide" class="urlextern" title="http://wiki.sourcemage.org/Git_Guide"  rel="nofollow">Git Guide</a>.
 335 </p>
 336
 337 </div>
 338 <!-- SECTION "How Do I ... ?" [6556-6679] -->
 339 <h3><a name="get_a_copy_of_geda_gaf_git_repository" id="get_a_copy_of_geda_gaf_git_repository">... get a copy of gEDA/gaf git repository?</a></h3>
 340 <div class="level3">
 341
 342 <p>
 343  For anonymous read-only access:
 344 </p>
 345 <pre class="code">$ git clone git://git.gpleda.org/gaf</pre>
 346
 347 <p>
 348  For developers with read/write access:
 349 </p>
 350 <pre class="code">$ git clone git://git.gpleda.org/home/git/gaf.git</pre>
 351
 352 </div>
 353 <!-- SECTION "... get a copy of gEDA/gaf git repository?" [6680-6899] -->
 354 <h3><a name="keep_my_local_copy_current" id="keep_my_local_copy_current">... keep my local copy current?</a></h3>
 355 <div class="level3">
 356
 357 <p>
 358  For those who are are not merging changes back into the central git repository you can run:
 359 </p>
 360 <pre class="code">$ git pull</pre>
 361
 362 <p>
 363  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:
 364 </p>
 365 <pre class="code">$ git fetch
 366 $ git rebase origin</pre>
 367
 368 </div>
 369 <!-- SECTION "... keep my local copy current?" [6900-7314] -->
 370 <h3><a name="commit_my_changes_to_the_local_git_repository" id="commit_my_changes_to_the_local_git_repository">... commit my changes to the local git repository?</a></h3>
 371 <div class="level3">
 372 <pre class="code">$ git commit -a </pre>
 373
 374 <p>
 375  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.
 376 </p>
 377
 378 <p>
 379 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:
 380 </p>
 381 <pre class="code">$ git commit filename1 filename2</pre>
 382
 383 </div>
 384 <!-- SECTION "... commit my changes to the local git repository?" [7315-7868] -->
 385 <h3><a name="undo_any_uncommitted_local_changes" id="undo_any_uncommitted_local_changes">... undo any uncommitted local changes?</a></h3>
 386 <div class="level3">
 387 <pre class="code">$ git checkout -f </pre>
 388
 389 <p>
 390  Note this will discard any changes to any files that are being tracked by git.
 391 </p>
 392
 393 </div>
 394 <!-- SECTION "... undo any uncommitted local changes?" [7869-8022] -->
 395 <h3><a name="fix_change_my_last_commit" id="fix_change_my_last_commit">... fix/change my last commit?</a></h3>
 396 <div class="level3">
 397 <pre class="code">$ Edit whatever files
 398 $ git commit --amend filename1..filenameN </pre>
 399
 400 <p>
 401  This will pickup any changes you made and recommit them again with the previous commit message.
 402 </p>
 403
 404 </div>
 405 <!-- SECTION "... fix/change my last commit?" [8023-] --></div>
 406 </body>
 407 </html>