gEDA Project Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
//Translations of this page are also available in the following languages:// [[scm.ru|Русский]].

====== gEDA uses git ======
gEDA uses **git** 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.
  * [[http://git.or.cz/|official git website]]
  * [[http://www.kernel.org/pub/software/scm/git/docs/|git documentation online]]

Some nice tutorials:
  * [[https://www.atlassian.com/git/tutorials/|comprehensive set of tutorials]] at atlassian.com
  * [[https://git.wiki.kernel.org/index.php/GitSvnCrashCourse|GitSvnCrashCourse]] -- git courses for SVN users
  * [[http://git.huit.harvard.edu/guide/ Git, the simple guide]] -- very concise and condensed cheat sheet style tutorial

===== Read-only access the geda repositories =====
To clone the geda-gaf.git repository (or any repository hosted at [[http://git.geda-project.org|git.geda-project.org]]) using anonymous git access:

  git clone git://git.geda-project.org/geda-gaf.git

or

  git clone git://git.geda-project.org/pcb.git

For different repositories hosted at git.geda-project.org, just substitute the last part of the above URL.

There is a [[http://hjemli.net/git/cgit/about/|cgit]] interface to the repositories of the various projects. Just point a www browser to [[http://git.geda-project.org/]] .

===== Feature branches =====
[[http://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell|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.

==== List all branches of a project ====
To list all branches of a project available on the geda-project server emit this command:
<code>$ git ls-remote git://git.geda-project.org/geda-gaf.git</code>

==== Track a feature branch ====
This will create a branch with the name ''<local name>'' in your local repository, which tracks the ''<remote name>'''d branch.
<code>$ git checkout --track -b <local name> origin/<remote name></code>
Go ahead and build the application]] from the branch as described by the [[geda:gaf_building_git_version|build instructions]]. By default the command ''make install'' will copy the binaries to ''/usr/local/*''. 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.

==== Communicate your experience ====
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.

For additional visibility you may report your experience on the mailing list [[geda:mailinglists|geda-user]]. 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.

===== Format a patch to send to the developers =====
The simplest possible way includes all changes since the local repository was syncronized with the repository at geda-project.org:
  $ git diff > name_of_patchfile

A more complicated way with more control on what the patch contains:
  $ git add -i           # select files to be committed
  $ git status           # check you're committing what you think you're committing
  $ git commit           # create a commit
  $ git format-patch -1  # create a patch file based on that commit
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.

===== Access the repository with write permission =====
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 //:65//):

  ssh://git@git.geda-project.org:65/<repository>.git

Note: If you're having trouble pushing commits upstream, make sure you're using git 1.5 or newer.

Accordingly, to grab a repository copy with write privileges you'd do this:

  git clone ssh://git@git.geda-project.org:65/<repository>.git

If you have a read-only clone already you can change it to one with write access:

  git remote remove origin
  git remote add origin ssh://git@git.geda-project.org:65/<repository>.git

Having this done, your local clone works just as before, just a ''git push origin <branch>'' succeeds.

==== Use a unique SSH key for gEDA ====

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:
<code>
Host git.geda-project.org
Port 65
IdentityFile ~/.ssh/gedaproject_dsa
</code>
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.

===== Commit changes =====

==== Set up user information ====
You should make sure that your username & e-mail address are set in your git configuration file.

  $ git config --global user.name "Your Name Comes Here"
  $ git config --global user.email you@yourdomain.example.com


==== Commit patches from other contributors ====
If you apply a patch from someone else (e.g. from a launchpad 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.

First of all, check a few things:
  * You have the latest version of the patch.
  * The author of the patch is happy for it to be committed (and wasn't still working on it)
  * That the you're happy with the patch, and taking responsibility for committing those changes.

For simplicity, start from an unmodified up-to date tree (git status shows no changes).

Apply the patch as usual (as an example):

  $ patch -p1 < example_changes.patch

You can also use the git apply command:

  $ git apply example_changes.patch

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.

<note>This is easy to miss accidentally if your editor introduces tabs. Please avoid letting it do so!</note>

For every file changed, added or removed, you need to inform git before it will commit the changes. To see the modified files, run:

  $ git status

For speed, the command:

  $ git add -u

will update all files which git tracks, including any files which were deleted.

For adding any new files the patch introduced, use the command

  $ git add new_file.c

Note: git add also takes wild-cards.

Commit the patch, making sure that the Author's name and e-mail address are specified:

  $ git commit --author "Author's Name Comes Here <author@example.com>"

As an alternative, you can set the GIT_AUTHOR_NAME and GIT_AUTHOR_EMAIL environment variables before issuing the normal commit command


==== Write good commit messages ====
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.

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.

**Do not** put a list of files changed into commit messages.  This information can be trivially obtained using the git tools.

Example:

<code>
Added new GedaList class derived from GObject

This abstracts a GList with API for write access. Its main use is in list
change notification, as it emits a "changed" g_signal when modified.
Read only access to the underlying GList is provided by an accessor,
currenly implemented as a macro.
</code>


===== Keep the local copy current =====
For those who are are not merging changes back into the central git repository you can run:

  $ git pull

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:

  $ git fetch
  $ git rebase origin

===== Commit changes to the local git repository =====
  $ git commit -a

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.

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:

  $ git commit filename1 filename2


===== Undo any uncommitted local changes =====
  $ git checkout -f

Note this will discard any changes to any files that are being tracked by git.

If you want to just discard edits in a single file, just run:

  $ git checkout path/to/file/to/discard

If you want to discard all edits from the current directory and downward recursively, just run:

  $ git checkout .


===== Fix a less than perfect last commit =====
  $ Edit whatever files
  $ git commit --amend filename1..filenameN

This will pickup any changes you made and recommit them again with the previous commit message.


===== Create a personalized branch =====
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 ''home/<user_name>/'', where ''<user_name>'' is your user name. 

First create the branch locally and simultaneously switch to it as the current branch:
   $ git checkout -b home/<user_name>/<name_of_the_branch>
Make some changes. Stage the changes and issue a commit:
   $ git stage <files to commit>
   $ git commit -F <commit_message>
Where ''<commit_message>'' points to a file which contains the commit message. 

To publish the changed branch to the remote repository do:
   $ git push origin home/<user_name>/<name_of_the_branch>
The first push to a branch creates it on the remote server.
For a little more convenience, you can advise git to always push to the current branch:
   $ git config --global push.default current
Skip the option ''<nowiki>--global</nowiki>'' if you want this to be active only in this particular git project. With this directive the command above reduces to a mere 
   $ git push
   
===== Delete a personalized branch =====
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:
   $ git push origin --delete home/<user_name>/<name_of_the_branch>
To delete the branch on the local repository, too:
   $ git branch --delete home/<user_name>/<name_of_the_branch>
   
===== Fetch a development branch from other people =====
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.

If you like to test one of the feature branches you have to fetch it from their repository.
The easiest way to get a branch is to use the fetch command.

    $ git fetch repository_url remote_branchname:local_branchname

**Examples:**
Getting the //cairo_experiment// branch from Peter C. would look like this:

    $ git fetch git://repo.or.cz/geda-gaf/pcjc2.git cairo_experiment:peters_cairo_experiment

Now you can switch to the local copy of the branch //peters_cairo_experiment// and play with it.

It is also possible to add multiple remote forks into the local repository:
    $ git remote add <name> <url>
    $ git fetch <name>
As long as <name> is unique you will be able to follow their work without the
need to create local branches. With a tool like gitk it is now possible to keep
an eye on development in various feature branches on various forks:
    $ gitk --all

**Examples:**
    $ git remote add peter-b https://github.com/peter-b/geda-gaf.git
    $ git fetch peter-b
    $ git remote add gareth8118 https://github.com/gareth8118/geda-gaf.git
    $ git fetch gareth8118
    $ git remote add bert https://github.com/bert/geda-gaf.git
    $ git fetch bert
    $ gitk --all

Now gitk can become quite filled up, but **File**->**List references** (<key>F2</key>) will open
a dialog for easier navigation.

Updating favourite remotes will then boil down to:
    $ git fetch --all

===== Recover from a really messed up local repository =====
First off, do not push any repository that you think is somehow messed up.  Ask one of the experienced git people first.

Second, the command that will really save your bacon is git-reflog.  Using it works something like this:

   $ git reflog
   086908e... HEAD@{0}: cherry-pick: Last minute updates to the READMEs for all pro
   2a79a23... HEAD@{1}: checkout: moving to master
   2a79a23... HEAD@{2}: checkout: moving to master
   ...
   $ git reset --hard HEAD@{1}

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.
gEDA Project Wiki

User Tools

Site Tools

Page Tools
