gEDA/gaf 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.

• Official git website
• git documentation online
• git Wikipedia page

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:

• gitk, a visual history repository browser
• Stacked Git, for working with patchsets

Debian-based

apt-get install git-core git-doc gitk stgit

you may also want:

apt-get install git-email git-completion

Fedora Linux

yum install git stgit

The toplevel documentation for git can be found at:

Official git docs

The user's manual for git can be found at:

git user manual

A current tutorial can be found at:

git core tutorial

Other nice tutorials/webpages:

Git Guide
git Crash Courses

Keep in mind that some of these tutorials are a little dated and may not cover current git syntax.

To clone the geda-gaf.git repository (or any repository hosted at 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 cgit interface to the repositories of the various projects. Just point a www browser to http://git.geda-project.org/ .

For developer git access, you should contact DJ Delorie to get your SSH public key installed; having done so, the git URL to push to is:

ssh://git@git.geda-project.org/geda-gaf.git

or

ssh://git@git.geda-project.org/pcb.git

You will also need to edit your ~/.ssh/config file (create it if it doesn't exist) and put the following text into it:

Host git.geda-project.org
Port 65

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

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

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!

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

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:

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.

Warning: pushing changes to the remote repository is destructive

Unlike CVS, it is not the committing of changes which changes the master repository, but pushing changes using git-push. You should always double- (or triple-) check that the commits you are about to push are actually meant for the main repository.

For a more information please checkout the Git Guide.

For anonymous read-only access:

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

For developers with read/write access:

$ git clone ssh://git@git.geda-project.org/geda-gaf

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

$ 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

$ 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 .

$ Edit whatever files
$ git commit --amend filename1..filenameN

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

$ git checkout --track -b <local name> origin/<remote name>

This will create a branch with the <local name> which tracks the <remote name>'d branch.

Run the following commands (using the stable-1.4 branch as an example):

 $ git branch stable-1.4 1.4.0-20080127
 $ git checkout stable-1.4
 <make changes>
 $ git commit -a

To publish this branch in the central repository (requires write access to the central repository):

 $ git push origin stable-1.4

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 (F2) will open a dialog for easier navigation.

Updating favourite remotes will then boil down to:

  $ git fetch --all

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.

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.