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.

Scribus Git Repositories
The full list of Scribus code Git repositories: 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, but 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)
 * scribus


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

Bases for Public Access
Public read-only access to all git repositories is available. For instance, to clone locally the trunk use the  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.

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


 * 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 git checkout -b --track footnotes origin/footnotes Rq : Sometime it seems that simply git checkout footnotes works better.
 * 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.
 * 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'

git checkout footnotes
 * Update local 'footnotes' branch

git pull 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
 * Compile as usual, but stating a dedicated destination folder. for example :

git pull
 * Pour ensuite actualiser localement le code afin de suivre les commits distants :

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  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,  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 synchronise 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

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

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

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

Literature on using Git
There are numerous Git tutorials on the web.


 * Official site : http://git-scm.com
 * Official documentation : http://git-scm.com/doc

These 2 make a very nice couple to start with too :
 * GitMagic : a complete documentation and tutorial
 * Gitref.org : git reference Project.

See also :
 * Introduction to Git @ github.
 * 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 ?

En français :
 * Le manuel de GIT à l'école de Stanford PDF complet, simple et bien écrit

Urgency Tricks
git fetch && git checkout -f -B thebranch origin/thebranch
 * If you have edited local changes and maybe tried to merge and couldnt because of conflicts, here is a way to localy recover git repo version of a 'unitLoader' branch (you will loose local changes ) :

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.