Git

This page provides documentation for the usage of Scribus Git repositories for Scribus development.

Introduction

Scribus Team maintains two code repositories - an internal protected Subversion repository accessible to only experienced core developers that contains a pristine history of Scribus development and a newer Git repository (several of them actually) that enable the Worldwide Scribus Community to easily contribute code to Scribus. We are attempting to follow the successful Git branching development model for the Git repository as explained below.

Definition for git commands can be found on http://git-scm.com/docs .

New summer 2014 Github repository !

A new git repo has been created on github. It mirrors and syncs svn repository and provides developement branches.

https://github.com/scribusproject/

Fork and code !

All continuing doc in this page is obsolete : described private git repository is not alive anymore.

Historical Contributors Git Repositories

The full list of Scribus code Git repositories:

• scribus

This is the main Scribus git repository with the complete history. This is where the developmental code written by the members of the Scribus Community happens. Please clone the repository and branch from the "master" branch to do your development, then push your branch to the repository for others to fetch.
It contains different branches:

   * master - mirror of the main development branch.  Do not push directly to this branch, instead 
              issue a pull request in #scribus or in the BTS.
   * trunk - branch synchronized with the Subversion trunk. Contains the contributors branches.

There can be some short lived feature branches there as well that may disappear at any time once merged into the master branch. For instance at this time there are:

   * footnotes - Adding Footnotes by cezaryece. Now merged into svn trunk, and git branch is dead.
   * autoheight - Work on the Frame auto-height by cezaryece.
   * statusbar - work on the statusbar by ale
   * epub and epub_modular : work on epub exporter by ale
   * numeration - work on paragraph effects like bullets, dropcaps and enumeration by cezariece. 
                  Now merged into the svn trunk.
   * imposer - work on PDF imposer by Foske
   * indic - work on indic text by Anil (see http://wiki.scribus.net/canvas/Complex_Script_Functionality)

• trunk - Repository for synchronization with the Subversion trunk. This is a read-only repository. It is used to provide current Scribus subversion/trunk code for Git users.
• testing - empty repository to practice and learn git. All members of the Scribus community are welcome to use it as needed. There is no guarantee that the changes will stay as another user can delete them just as easily as they are created.

GSoC 2012 Student repositories:

• gsoc12pm - Project Manager project repository.
• gsoc12ux - User Experience project repository.
• gsoc12xml - New XML File Format project repository.
• gsoc12trunk - Merge and synchronization repository for GSoC 2012 (unused)

The GSoC repositories are writable by the students and their mentors, but are also available as read-only repositories for anyone else using the "Public Access" method described below.

Using Scribus Git Repositories

Bases for Public Access

WARNING : Examples given are for historical "contributors" repos. Adresses are OUT OF DATE. See elsewhere in page for uptodate urls.

Public read-only access to all git repositories is available. For instance, to clone locally the trunk use the git clone git://git.scribus.net/trunk.git command. It will create a local repository from a copy of the at the time distant repo.

Note : after installing git, the whole procedure is as follows. Real commands to follow are marked with a dot, other lines are examples.

• Get the whole code for the repository (see http://git-scm.com/docs/git-clone for details on command)

git clone git://git.scribus.net/scribus.git

If you want to clone into a scribus.git folder the command is

git clone git://git.scribus.net/scribus.git scribus.git

For ScribusECE repository (http://www.scribus-ece.info = cezaryece's scribus enhanced version), you'll create a local copy of the repo in the 'ece' folder using the following command :

git clone git://scribus-ece.info/ScribusECE ece

List local branches. See: current is *master. (see http://git-scm.com/docs/git-branch for options details)

git branch

List all remote branches (notice the branch are labelled with an 'origin/' prefix)

git branch -r

List all branches on the repo (local AND remote) :

git branch -a

• Create local branch to follow distant branch, for example footnote branch (see http://git-scm.com/docs/git-checkout for options). This branch becomes the active one.

git checkout -b footnotes --track origin/footnotes

Rq : Sometime it seems that 'checkout footnotes' simply works better i.e. git checkout footnotes

list all local branches ( current is now *footnotes, other is master) :

git branch

Change local active branch to master for example.

git checkout master

Update 'master' branch

git pull

Set local active branch back to 'footnotes', even if you have previously edited some files in this branch :

git checkout -f footnotes

Update local 'footnotes' branch

git pull

• Compile as usual, but stating a dedicated destination folder. for example :

 cd Scribus
 mkdir build
 cd build
 cmake -DCMAKE_INSTALL_PREFIX:PATH=~/bin/scribusfootnotes -DWANT_DEBUG=1 -DWANT_GUI_LANG="fr" -DWANT_SYSTEM_CAIRO=1 ..
 make -j4
 sudo make install
 sudo ln -s ~/bin/scribusfootnotes/bin/scribus /usr/bin/scribusfootnotes

• Pour ensuite actualiser localement le code afin de suivre les commits distants :

git pull

Write Access

Read the Set up SSH Keys section to learn about creating an acceptable ssh key. On Linux, your public ssh key can then be found in "~/.ssh/id_rsa.pub".

To obtain write access please email your public ssh key to admin@scribus.net or post it somewhere on the web and email or paste the link into #scribus IRC channel (and ask Malex to find it !).

Once we accept your key you will be able to verify your access with a ssh git@git.scribus.net info command.

If you have access gitolite will greet you and show the list of repositories accessible to you. After that, you can clone a repository via, for example, git clone git@scribus.net:scribus.git and be able to push back your commits if allowed.

(AS OF NOW THIS MIGHT BE DIFFERENT) The application of the Git Branching and Merging development model to Scribus development includes :

• Using scribus.git repository for community development.
• Using the following naming scheme for the branches:
  • master - main developmental branch - merge your feature/fix branches into it.
  • release - release / tagging branch.
  • trunk - used to synchronize code to and from the git-svn trunk.git repository.
  • YOURBRANCH - branch master and develop new features or fix problems before merging into master.

Updating a branch

So as to synchronize your local repo with the distant one, you have to pull:

git pull

if you only want to checkout footnotes branc, you might try :

git pull origin footnotes

In case you have modified local repo, its not possible anymore to pull. In such a situation, git status tells what files are changed in the local repo. You can then revert file to state from remote repo with :

git checkout remote/repo -- file

Good git diffs & svn patchs

How to create a good diff

This still has to be defined.

How to apply a diff

This still has to be documented. Begin !

SVN vs GIT diffs

Ch: The only difference between git diff file and svn diff file is that you have to use patch -p1 instead of patch -p0 to apply them.

Cz: The trick with diffs from git is to use : --no-prefix switch

git diff --no-prefix remote/branch my_branch

and I am always using trunk/svn as remote for diff and now diff file is working with

#patch -l -p0 < file.diff

Patch for windows OS (to be further explored)

• http://docs.moodle.org/dev/How_to_apply_a_patch#Apply_a_Patch_in_Windows_using_gnuwin32
• http://gnuwin32.sourceforge.net/packages/patch.htm

Example to sum it up : how to get and compile a specific branch : indic of scribus.git

In case you want to build another branch of scribus.git, replace indic with the name of the branch in all occurences.

In case the branch you want to build is another repo, replace scribus.git with the name of the repo.

The build is done quicker using the -DWANT_GUI_LANG="en" option for the cmake command. If you want a french-only interface instead of an english-only, use -DWANT_GUI_LANG="fr". If you want access to all langages in the interface, juste dont take that option out of the cmake command (but building time will be much longer).

cd ~
mkdir dev
cd dev
mkdir scribus
cd scribus
git clone git://git.scribus.net/scribus.git scribus.git
cd scribus.git
git checkout indic
git pull
cd Scribus
mkdir buildindic
cd buildindic
mkdir ~/bin
mkdir ~/bin/scribusindic
cmake -DCMAKE_INSTALL_PREFIX:PATH=~/bin/scribusindic -DWANT_DEBUG=1 -DWANT_GUI_LANG="en" -DWANT_SYSTEM_CAIRO=1 ..
make -j4
sudo make install
sudo ln -s ~/bin/scribusindic/bin/scribus /usr/bin/scribusindic

In case you got missing libraries error, here is how you should get them all :

sudo apt-get build-dep scribus
sudo apt-get install libqtwebkit4 libqtwebkit-dev
sudo apt-get install libicu48 libicu-dev
sudo apt-get install git

Currently, you might have to install a more recent version of libicu:

sudo apt-get install libicu52

You might have to also:

sudo apt-get install liblcms1-dev

It has been reported that without it, the indic branch won't compile. It's not clear at this point, if it's an extra dependency of the indic branch (very unlikely) a library that has been replaced in the main Scribus code (by a newer version) or simply a miss in the documentation on how to compile Scribus from source.

Tools for GIT

On linux, there are plenty of tools. Just to name a few :

• rabbitvcs provides a nautilus extension a bit like tortoise tools
• gitg enables to view nicely the branch trees, to easily browse across the branches and to view each commit details.
• QGit does the same but doesnt look so friendly.

Fewer tools are available for windows : msysgit

Documents and tutorials on using Git

There are numerous Git tutorials on the web.

• Official site : http://git-scm.com
• Official documentation : http://git-scm.com/doc : both the official reference manual and the Git Pro book (also exists in french)

These 2 make a very nice couple to start with along with :

• GitMagic : a complete documentation and tutorial
• Gitref.org : git reference Project.
• GIT Concepts Simplified

This interactive single page shows datastructure and hints for all commands, in english or french.

• http://ndpsoftware.com/git-cheatsheet.html#loc=remote_repo;

See also :

• Introduction to Git @ github.
• GIT from the bottom up
• Good Git tutorial
• Git Immersion.
• Easy Version Control with Git.
• A visual Git reference.
• Git-svn crash course to learn how to work with subversion via Git.
• Explain concepts through Git internal graphs. Usefull for 'rebase' particularly.
• Explain from SVN to GIT ?
• Logical action chart on how to escape a git mess

En français :

• Le manuel de GIT à l'école de Stanford PDF complet, simple et bien écrit

Specific issues :

• how to not commit a 'merge' commit when merging

Urgency Tricks

If you have edited local changes and maybe tried to merge and couldn't because of conflicts, here is a way to locally recover git repo version of a 'unitLoader' branch (you will loose local changes ) :

git fetch && git checkout -f -B thebranch origin/thebranch

if it's not ok (because of whatever conflict or history issue), this should sort out the issue :

git reset --hard HEAD && git fetch && git checkout origin/unitLoader && git checkout -b lala && git branch -M unitLoader

Explanations : remove current change (because a merge was allredy tempted), then fetch original repo, go on this repo (without branch), create a fake branch (lala) and then remove this branch to call is : unitLoader

Neither GIT not SVN but Scribus too

• https://bitbucket.org/balpha/scribus-patches/wiki/Home : set of patches to enhance scribus, with a Mercurial repo.