Git: Difference between revisions

From Scribus Wiki
Jump to navigation Jump to search
 
(38 intermediate revisions by 3 users not shown)
Line 7: Line 7:
Definition for git commands can be found on http://git-scm.com/docs .
Definition for git commands can be found on http://git-scm.com/docs .


==Scribus Git Repositories==
== 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:
The full list of Scribus code Git repositories:
* scribus
* 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. <br>
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. <br>
It contains different branches:  
It contains different branches:  
     * master - main development branch. Do not push directly to this branch, but issue a pull request in #scribus or in the BTS.
     * master - mirror of the main development branch. Do not push directly to this branch, instead
     * trunk - branch synchronized with the Subversion trunk.
              issue a pull request in [[Special:WebChat|#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:
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.
     * footnotes - Adding Footnotes by cezaryece. Now merged into svn trunk, and git branch is dead.
Line 19: Line 30:
     * statusbar - work on the statusbar by ale
     * statusbar - work on the statusbar by ale
     * epub and epub_modular : work on epub exporter 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.
     * numeration - work on paragraph effects like bullets, dropcaps and enumeration by cezariece.  
     * imposer : work on PDF imposer by Foske
                  Now merged into the svn trunk.
     * indic : work on indic text by Anil
     * 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.
* 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.
Line 36: Line 48:
==Using Scribus Git Repositories==
==Using Scribus Git Repositories==
===Bases for Public Access===
===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 <code>git clone git://git.scribus.net/trunk.git</code> command. It will create a local repository from a copy of the at the time distant repo.
Public read-only access to all git repositories is available. For instance, to clone locally the trunk use the <code>git clone git://git.scribus.net/trunk.git</code> command. It will create a local repository from a copy of the at the time distant repo.


Line 42: Line 57:


* Get the whole code for the repository (see http://git-scm.com/docs/git-clone for details on command)
* 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
<code>git clone git://git.scribus.net/scribus.git</code>


:If you want to clone into a scribus.git folder the command is  
:If you want to clone into a scribus.git folder the command is  
  git clone git://git.scribus.net/scribus.git scribus.git
<code>git clone git://git.scribus.net/scribus.git scribus.git</code>


: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 :
: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
<code>git clone git://scribus-ece.info/ScribusECE ece</code>


:List local branches. See: current is *master. (see http://git-scm.com/docs/git-branch for options details)
:List local branches. See: current is *master. (see http://git-scm.com/docs/git-branch for options details)
  git branch
<code>git branch</code>
 
:List all remote branches (notice the branch are labelled with an 'origin/' prefix)
:List all remote branches (notice the branch are labelled with an 'origin/' prefix)
  git branch -r
<code>git branch -r</code>
 
:List all branches on the repo (local AND remote) :
:List all branches on the repo (local AND remote) :
  git branch -a
<code>git branch -a</code>
* 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.
* 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 --track footnotes origin/footnotes
<code>git checkout -b footnotes --track origin/footnotes</code>
Rq : Sometime it seems that simply
 
  git checkout footnotes
Rq : Sometime it seems that 'checkout footnotes' simply works better i.e.
works better.
<code>git checkout footnotes</code>
 
:list all local branches ( current is now *footnotes, other is master) :
:list all local branches ( current is now *footnotes, other is master) :
  git branch
<code>git branch</code>
 
:Change local active branch to master for example.
:Change local active branch to master for example.
  git checkout master
<code>git checkout master</code>
 
:Update 'master' branch
:Update 'master' branch
  git pull
<code>git pull</code>
:Set local active branch back to 'footnotes'
 
  git checkout footnotes
:Set local active branch back to 'footnotes', even if you have previously edited some files in this branch :
<code>git checkout -f footnotes</code>
 
:Update local 'footnotes' branch
:Update local 'footnotes' branch
  git pull
<code>git pull</code>
 
* Compile as usual, but stating a dedicated destination folder. for example :
* Compile as usual, but stating a dedicated destination folder. for example :
   cd Scribus
   cd Scribus
Line 81: Line 104:


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


===Write Access===
===Write Access===
Line 102: Line 125:


=== Updating a branch ===
=== Updating a branch ===
So as to synchronize your local repo with the distant one, you have to pull:
<code>git pull</code>


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 :
if you only want to checkout footnotes branc, you might try :
  git pull origin footnotes
 
<code>git pull origin footnotes</code>


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 :
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
 
<code>git checkout remote/repo -- file</code>


===Good git diffs & svn patchs===
===Good git diffs & svn patchs===
Line 124: Line 150:
===== SVN vs GIT diffs =====  
===== 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.
'''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
 
<code>git diff --no-prefix remote/branch my_branch</code>


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 I am always using trunk/svn as remote for diff
and now diff file is working with  
and now diff file is working with  
  #patch -l -p0 < file.diff
 
<code>#patch -l -p0 < file.diff</code>


===== Patch for windows OS (to be further explored) =====
===== Patch for windows OS (to be further explored) =====
Line 136: Line 165:
* http://gnuwin32.sourceforge.net/packages/patch.htm
* http://gnuwin32.sourceforge.net/packages/patch.htm


==To sum it up : how to get and compile a specific branch : indic of scribus.git ==
==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 you want to build another branch of scribus.git, replace indic with the name of the branch in all occurences.


Line 171: Line 200:
sudo apt-get install git
sudo apt-get install git
</pre>
</pre>
Currently, you might have to install a more recent version of libicu:
<pre>
sudo apt-get install libicu52
</pre>
You might have to also:
<pre>
sudo apt-get install liblcms1-dev
</pre>
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 ==
== Tools for GIT ==
Line 177: Line 217:
Just to name a few :
Just to name a few :
* rabbitvcs provides a nautilus extension a bit like tortoise tools
* rabbitvcs provides a nautilus extension a bit like tortoise tools
* gitg provides a very usefull tool to view the branch trees, to easily browse across the branches and to view each commit details. QGit does the same but doesnt look so friendly.
* 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
Fewer tools are available for windows : msysgit


==Literature on using Git==
==Documents and tutorials on using Git==
There are numerous Git tutorials on the web.
There are numerous Git tutorials on the web.


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


These 2 make a very nice couple to start with too :
These 2 make a very nice couple to start with along with :
* [http://www-cs-students.stanford.edu/~blynn/gitmagic/intl/fr GitMagic : a complete documentation and tutorial]
* [http://www-cs-students.stanford.edu/~blynn/gitmagic/intl/fr GitMagic : a complete documentation and tutorial]
* [http://gitref.org/index.html Gitref.org : git reference Project].
* [http://gitref.org/index.html Gitref.org : git reference Project].
* [http://gitolite.com/gcs.html#%281%29 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 :
See also :
* [http://learn.github.com/p/intro.html Introduction to Git @ github].
* [http://learn.github.com/p/intro.html Introduction to Git @ github].
* [http://jwiegley.github.io/git-from-the-bottom-up/ GIT from the bottom up]
* [http://www.codeschool.com/courses/try-git Good Git tutorial]
* [http://gitimmersion.com/ Git Immersion].
* [http://gitimmersion.com/ Git Immersion].
* [http://net.tutsplus.com/tutorials/other/easy-version-control-with-git/ Easy Version Control with Git].
* [http://net.tutsplus.com/tutorials/other/easy-version-control-with-git/ Easy Version Control with Git].
Line 199: Line 246:
* [http://eagain.net/articles/git-for-computer-scientists Explain concepts through Git internal graphs. Usefull for 'rebase' particularly.]
* [http://eagain.net/articles/git-for-computer-scientists Explain concepts through Git internal graphs. Usefull for 'rebase' particularly.]
* [http://www.electronicsweekly.com/blogs/open-source-linux/2009/03/git---version-control-for-grumpy-old-men.html Explain from SVN to GIT ?]
* [http://www.electronicsweekly.com/blogs/open-source-linux/2009/03/git---version-control-for-grumpy-old-men.html Explain from SVN to GIT ?]
* [http://justinhileman.info/article/git-pretty/git-pretty.png Logical action chart on how to escape a git mess]
En français :
* [http://www-cs-students.stanford.edu/~blynn/gitmagic/intl/fr/book.pdf Le manuel de GIT à l'école de Stanford] PDF complet, simple et bien écrit
Specific issues :
* [http://kernowsoul.com/blog/2012/06/20/4-ways-to-avoid-merge-commits-in-git/ 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 ) :
<code>git fetch && git checkout -f -B thebranch origin/thebranch</code>
if it's not ok (because of whatever conflict or history issue), this should sort out the issue :
<code>git reset --hard HEAD && git fetch && git checkout origin/unitLoader && git checkout -b lala && git branch -M unitLoader</code>
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.

Latest revision as of 11:58, 15 December 2014

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.

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

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)

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.

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

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

See also :

En français :

Specific issues :

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