This page provides documentation for the usage of Scribus Git repositories for Scribus development.
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, 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
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)
- 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) :
- Change local active branch to master for example.
git checkout master
- Update 'master' branch
- 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
- 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 :
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 firstname.lastname@example.org 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 email@example.com 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 firstname.lastname@example.org: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:
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)
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
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 too :
This interactive single page shows datastructure and hints for all commands, in english or french.
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 ?
- 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
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.