Dolibarr ERP CRM Wiki

Changes

FAQ Get,update GIT project sources (view source)

Revision as of 09:49, 2 April 2025

13,017 bytes added ,  1 month ago
m
→‎Ask official project to include your changes (PR)
Line 1: Line 1:  +
<!-- BEGIN origin interlang links -->
 +
<!-- You can edit this section but do NOT remove these comments
 +
    Links below will be automatically replicated on translated pages by PolyglotBot -->
 +
[[fr:FAQ_Récupérer,_mettre_à_jour_les_sources_GIT_du_projet]]
 +
[[es:FAQ_Recuperar,_actualizar_GIT_fuentes_del_proyecto]]
 +
[[de:FAQ_Get,_update_GIT_Projekt_Quellen]]
 +
[[zh:常见问题-获取与更新项目的GIT源代码]]
 +
<!-- END interlang links -->
 +
 
[[Category:FAQ EN]]
 
[[Category:FAQ EN]]
 
{{TemplateDocDevEn}}
 
{{TemplateDocDevEn}}
−
This is informations on how you can get sources of Dolibar project.
+
This is information on how you can get sources of Dolibarr project using GIT.
 +
Several methods are described, but we recommand using the one with a GitHub user account.
 +
 
 +
<br />
 +
 
 +
=Get last version of sources by tgz download=
 +
This method can be used by non technical users.
 +
It allows you to get sources of main development branch (called HEAD) by just downloading a file: This operation consist to get last version of Dolibarr files that are packaged each night into a tgz file. File is available with link:
 +
 
 +
{{LinkLastSnapshot}}
 +
 
 +
New files overwrite old ones.
 +
The inconvenient of this method is that you must download and uncompress package each time you want to get updates.
 +
 
 +
Developers should not use this method to get sources but the next one.
    
=Get last version of sources using a GIT anonymous access=
 
=Get last version of sources using a GIT anonymous access=
 +
You can use this method if you don't have any GIT access. With this method, you won't be able to submit any changes, so, if you are a developer, it is recommended to create a GitHub account and use the next method instead of this one.
 +
 +
==Prerequisite==
   −
To get sources with goal to edit them, you need a GitHub write access to the GIT remote repository, and a GIT client (GIT command line tool with Linux, or the GIT client in Eclipse).
+
*With Eclipse IDE
   −
First add repostiroy on your GIT client tool.
+
First you must have a working install of Eclipse. '''EGit''' plugin must also have been installed.
−
With Eclipse, choose "Clone GIT repository" for this GIT URL:
+
For this, use the '''Find And Install process''' into Eclipse menu, add the GIT update URL:  
−
git://github.com/Dolibarr/dolibarr.git
+
https://download.eclipse.org/egit/updates
 +
Then choose to install '''EGit''' (No need to choose JGit)
   −
Choose the branches you are interesting in. Branches not selected now could be selected later by doing a "Fetch" from the "Remotes" view.
+
*With the GIT Command Line Client Interface
   −
=Get last version of sources using a full GIT access=
+
You need to install GIT client (GIT command line tool with Linux installed with "sudo apt-get install git", or the GIT client for Windows found at https://git-scm.com/download/win).
   −
To get sources with goal to edit them, you need a GitHub write access to the GIT remote repository, and a GIT client (GIT command line tool with Linux, or the GIT client in Eclipse).
+
==Clone process==
 +
First, enter value of the repository with reference sources into your GIT client tool.
   −
First add repository on your GIT client tool.
+
*With Eclipse, go into perspective GIT, click onto button "Clone GIT repository". Enter GIT URL of project to get.
−
With Eclipse, choose "Clone GIT repository" for this GIT URL:
  −
https://yourgitlogin@github.com/Dolibarr/dolibarr.git
     −
Choose the branches you are interesting in. Branches not selected now could be selected later by doing a "Fetch" from the "Remotes" view.
+
GIT Url for Dolibarr official source is:
 +
<source lang="ini">
 +
git://github.com/Dolibarr/dolibarr.git (read only)
 +
or if you created a fork of dolibarr github from github web interface
 +
git@github.com:yourgitaccount/dolibarr.git (read and write access)
 +
</source>
 +
Your Eclipse GIT client will ask you to choose the branches you are interested in. Branches not selected now could be selected later by doing a "Fetch" from the "Remotes" view, but try to choose only the branch you need. This will save you time and problems later.
   −
Once remote repository is linked into your client software, you must create a local branch.
+
Note: if you are behind a firewall, you must set Eclipse proxy credentials into Eclipse menu Windows - Preferences - General - Network connection and use the alternative URL:
−
From GIT view, rigth click on "Branches - Remotes - The branch you want to duplicate locally".
+
<source lang="ini">
−
If you Choose "Checkout", this will update the view "Working Directory".
+
https://gitlogin:gitpassword@github.com/yourgitaccount/dolibarr.git
−
If you choose "Create Branch", this will duplicate content of branch to work on it locally.
+
</source>
   −
=Get complementary modules=
+
*With GIT on Command Line Interface:
−
A CVS repository for non official or rare Dolibarr modules is also available into CVS module dolibarrmod
  −
See page to knwo how to extract sources from CVS [[FAQ Get,update project sources]].
      +
First setup your git client:
 
<source lang="bash">
 
<source lang="bash">
−
CVSROOT=:ext:yoursavannahlogin@cvs.savannah.nongnu.org:/cvsroot/dolibarr
+
git config --global user.name "Your Name"
−
export CVSROOT
+
git config --global user.email "user@domain.com"
−
cvs -q checkout -r HEAD dolibarrmod
+
git config --list
 +
</source>
 +
Then clone repository locally:
 +
<source lang="bash">
 +
git://github.com/Dolibarr/dolibarr.git (read only)
 +
or if you created a fork of dolibarr github from github web interface
 +
git@github.com:yourgitaccount/dolibarr.git (read and write access)
 +
</source>
 +
 
 +
Note: if you are behind a firewall, you must set your porxy information and use the alternative https URL:
 +
<source lang="bash">
 +
git config --global http.proxy http://proxyuser:proxypass@proxyserver:proxyport
 +
git clone https://gitlogin:gitpassword@github.com/yourgitaccount/dolibarr.git dolibarr
 +
</source>
 +
 
 +
Once this step is validated, your GIT client will download all files from remote GIT server. This may last several seconds or minutes.
 +
 
 +
Once download is finished, you must choose which branch to us to work on.
 +
 
 +
*With GIT on Command Line Interface;
 +
 
 +
<source lang="bash">
 +
git checkout develop
 +
git checkout x.y
 +
</source>
 +
This will create local branch and make checkout automatically.
 +
 
 +
*With Eclipse, right click on "Branches - Remotes - The branch you want to duplicate locally".
 +
 
 +
Choose "Create Branch" (and check the box "Checkout"). This will duplicate content of branch to work on it locally and will refresh your "Working Directory" to work on this branch.
 +
 
 +
Create Eclipse project:
 +
 
 +
If using Eclipse, once your branch is created locally, create a PHP project from assistant by choosing "'''Create from existing project'''" and select directory that is your GIT local repository (Do not choose to create a PHP project from scratch).
 +
Then right click on project from your Eclipse workspace and Choose "'''Team - Share'''". Select GIT and click on option "'''Use or create repository in parent folder of project'''".
 +
An alternate method is File->Import, Git->Project from Git, Select the Git repository and Next, Use New project Wizard -> Php project, enter the folder of you GIT local repository.
 +
 
 +
Then, you can setup Eclipse to avoid it to scan all project files for its build tools (Outline scanner, TODO scanner, syntax scanner...). This will avoid Eclipse to be too slow. For this, right click on project, choose Build Path and setup it like into following screenshot.
 +
 
 +
[[File:Eclipse php build path.png|240px]]
 +
 
 +
=Get last version of sources using a GitHub user access=
 +
==Prerequisite==
 +
 
 +
*With Eclipse IDE
 +
 
 +
You must before create an account on GitHub (https://github.com/) and upload a public RSA or DSA certificate into your account profile.
 +
 
 +
Then, you must have a working install of Eclipse. '''EGit''' plugin must also have been installed (this is the case by default on any recent Eclipse version).
 +
For this, use the '''Find And Install process''' into Eclipse menu, add the GIT update URL:
 +
https://download.eclipse.org/egit/updates
 +
Then choose to install '''EGit'''.
 +
 
 +
*With the GIT Command Line Client Interface:
 +
 
 +
You must before create an account on GitHub (https://github.com/) and upload a public RSA or DSA certificate into your account profile.
 +
 
 +
Then, you need to install GIT client (GIT command line tool with Linux installed with "sudo apt-get install git", or the GIT client for Windows found at https://git-scm.com/download/win).
 +
 
 +
==Fork process==
 +
Login to Github, with login you created in previous step. Then go onto page
 +
 
 +
https://github.com/Dolibarr/dolibarr
 +
 
 +
And click on button "Fork".
 +
 
 +
This will create a copy (a fork) of project into your own github area. Because you will be the owner of this fork, you will have all permissions on it to be used in next steps.
 +
 
 +
==Clone process==
 +
Then process is same as getting sources with anonymous access.
 +
 
 +
URL to use for GIT clone is same:
 +
<source lang="ini">
 +
git@github.com:YourGitHubLogin/dolibarr.git
 
</source>
 
</source>
 +
 +
Note that a HTTPS URL is also available but it's sometimes offline (so prefer using first one, link with HTTPS is required only if you are behind a firewall):
 +
 +
<source lang="ini">
 +
https://yourgithublogin@github.com/Dolibarr/dolibarr.git
 +
</source>
    
=Update your repository=
 
=Update your repository=
 +
To update your local workspace:
   −
The command to update files that was caught with previous CVS command:
+
*With Eclipse IDE:
 +
 
 +
right click on Eclipse project and select "Pull".
 +
 
 +
If you made some changes into your Eclipse workspace on files that were changed into the GIT remote reference, your GIT client will make a merge automatically.
 +
 
 +
*If there is conflicts, the merge will mark all conflict files as "conflict" (See later to solve this state).
 +
*If not, you will get all new version files including all your changes.
 +
 
 +
If you already have commited some files into your local repository, your workspace will be marked as "Merged".
 +
All you have to do is make a commit to validate your local repository as including your changes and changes made by others.
 +
 
 +
 
 +
*With the GIT Command Line Client Interface:
   −
''With linux:''
   
<source lang="bash">
 
<source lang="bash">
−
cvs -q update -P -d
+
git pull
 
</source>
 
</source>
−
''With Windows and Tortoise cvs''
+
 
 +
=Commit and publish your changes=
 +
To see all changes you made into your working directory and waiting to be added into Git:
 +
 
 +
*With GIT Command Line Interface:
 +
 
 +
<source lang="bash">
 +
git status
 +
git diff subdir/filename
 +
</source>
 +
 
 +
To add changes made into your local repository into the GIT index, then commit this index :
 +
 
 +
*With Eclipse: Right click on file or directory to commit. Select file to add/remove/update into commit.
 +
*With GIT Command Line Interface:
 +
 
 +
<source lang="bash">
 +
git commit -a -m "Commit text"
 +
</source>
 +
This will save add and changes into your local branch.
 +
 
 +
To push them on the GIT repository server,
 +
 
 +
*With Eclipse: right click on project and choose "'''Team - Push to Upstream'''".
 +
*With GIT Command Line Interface:
 +
 
 
<source lang="bash">
 
<source lang="bash">
−
"C:\Program Files\CVSNT\cvs.exe" -q update -P -d
+
git push
 
</source>
 
</source>
−
And to set back all your working directory with same files than on CVS server repository (canceling your local changes):
     −
''With linux:''
+
To cancel a commit:
 +
 
 +
*With GIT Command Line Interface, if commit was not already pushed:
 +
 
 
<source lang="bash">
 
<source lang="bash">
−
cvs -q update -P -C -d
+
git reset --soft HEAD~1
 
</source>
 
</source>
−
''With Windows and Tortoise cvs''
+
 
 +
*With GIT Command Line Interface, if commit was already pushed:
 +
 
 
<source lang="bash">
 
<source lang="bash">
−
"C:\Program Files\CVSNT\cvs.exe" -q update -P -C -d
+
git revert IdCommit  or  git revert HEAD  (for last commit)
 
</source>
 
</source>
   −
May be, you will have to change permissions on directories or files after to make then readable by users of your Dolibarr web server.
+
To merge changes done into your forked GIT instance into official Dolibarr instance:
   −
=Get files for a particular CVS branch=
+
*Go into GitHub web interface of your forked Git instance.
 +
*Click on small button "Create a Pull request".
 +
*Choose commit you request inclusion and validate.
   −
If you want to work on a particular version (with its patches), you must follow same process but you must replace HEAD by name of the branch.
+
=Ask official project to include your changes (PR) =
−
For example DOLIBARR_2_2_BRANCH for branch 2.2 or DOLIBARR_2_4_BRANCH for branch 2.4.
+
Once you pushed one or several commit toward your distant fork area on github, you can ask the Dolibarr core team to include it into official project. We call this "making a Pull or a Merge request" also called "PR" or "MR".
 +
For this, follow this tutorial: https://help.github.com/articles/creating-a-pull-request/
   −
=Get last version of sources by download=
+
Note that you can request to include your change inthe develop branch or into a stable branch if this is a bug fix. The following chart show you how the core team decide if a PR is merged into a maintenance or the develop branch: [[:Category:RoadMap#Merging_PR_process_.28develop_or_maintenance_.3F.29]]
 +
 
 +
=Add a given external commit into your current repository=
 +
Some developers may work and do commit into their own Git repository after forking the project. If you are interesting into getting this changes, you can import them with the following steps.
 +
 
 +
You need both Eclipse and GIT Command Line interface to achieve this:
 +
 
 +
*First, go into GIT setup view and right click on "'''Remotes'''" of your Eclipse Git working space and choose "'''Create a remote...'''"
 +
*Type name or remote fork the developer has create (in most cases, it's developer Git login). For example: "'''thedevlogin'''". Choose also "'''Configure Fetch'''".
 +
*Type URI of Git repository of developer. For example: '''git://github.com/thedevlogin/dolibarr.git'''. Also add a refspec value to declare the branch you want to get. For example: '''refs/heads/master:refs/remotes/thedevlogin/master'''. Click "'''Save and Fetch'''". A new entry will be added into "Remote Tracking" making possible to read/get commits done into this branch.
 +
 
 +
Now, go on command line of your git repository (in most cases on Linux, it's '''/home/yourlogin/git/yourdolibarr''') and type the git cherry-pick command:
 +
<source lang="bash">
 +
git cherry-pick -x commitid
 +
</source>
 +
where commitid is value of commit id you want to get.
 +
 
 +
Once this is done, go back to Eclipse and make a refresh on project. You will see modified files appears with decorators (with conflicts if there is).
 +
 
 +
It the cherry-pick fails because of conflicts, you can cancel the cherry-pick try with
 +
<source lang="bash">
 +
git cherry-pick --abort
 +
</source>
 +
 
 +
=Solving a conflict=
 +
If a file has been marked as "conflict" after a Pull, open the file to edit it.
 +
Find string "<<<<<<<<<<", you will see part of code that is conflict between "<<<<<<<<<" and ">>>>>>>>". Edit manually code lines and remove "<<<<<<<<" and ">>>>>>>".
 +
 
 +
Then, right click on file and select "Add".
 +
 
 +
If you prefer to forget completely all changes you made into all files (so to restore you workspace with content of remote repository), you can make a hard reset:
 +
 
 +
*With Eclipse: Right click on project top line and select "'''Reset'''" then "'''Hard'''" then "'''Reference - HEAD'''".
 +
*With GIT Command Line Interface: You can achieve this with command
 +
 
 +
<source lang="bash">
 +
git reset --hard HEAD
 +
</source>
 +
To reset changes you commited but not pushed to origin
 +
<source lang="bash">
 +
git reset --hard origin/develop
 +
</source>
 +
 
 +
=Tagging sources=
 +
With GIT Command Line Interface:
 +
 
 +
To add a tag to a current version:
 +
<source lang="bash">
 +
git tag -a -m "Release|Maintenance release x.y.z" "x.y.z"
 +
or
 +
git tag -a -f -m "Beta x.y.betai" "x.y.betai_YYYYMMDD" idcommit  # -f force if an existing tag already exists, idcommit allows to choose commit to tag
 +
 
 +
git push --tags  # To push tags to remote origin
 +
</source>
 +
 
 +
To remove a tag:
 +
<source lang="bash">
 +
git tag -d "x.y.z_YYYYMMDD"
 +
git push remoteentryname :x.y.z_YYYYMMDD    # To validate delete on remote origin
 +
</source>
 +
 
 +
=Creating a new branch=
 +
With GIT Command Line Interface:
 +
 
 +
Create a clone (see previously) of the branch from where you want to create another branch, then go into directory and launch command:
 +
<source lang="bash">
 +
git branch x.y
 +
git push origin x.y
 +
</source>
 +
 
 +
With Eclipse:
 +
 
 +
Create a clone (see previously) of the branch from where you want to create another branch, with a checkout done. The go into view git. Choose branches, remote tracking and select start branch.
 +
Right click and choose "Create branch".
 +
Then make a push to create branch remotely.
 +
Then go into "Remotes - origins" and edit the entries to pull and push onto new branch.
 +
It may also be required to edit the .git/config file to have project linked by default onto new branch.
 +
 
 +
=Deleting a branch=
 +
With GIT Command Line Interface:
 +
 
 +
Do a push on branch but add : before name of branch:
 +
<source lang="bash">
 +
git push remoteentryname :branchnametodelete
 +
</source>
 +
 
 +
=Merging a maintenance branch x.x into dev branch=
 +
With Eclipse:
 +
 
 +
*Go onto the root directory of project with a checkout of the dev branch.
 +
*Check fetch setup to be sure, this repository contains both information of dev branch and version x.x you want to merge.
 +
*Right click onto root directory and choose "Team - Merge". Select "x.x". Click onto "Merge options - Commit", because we want to commit merged branch if there is no conflicts.
 +
*Once merge is done, check everything is ok.
 +
*Commit and push.
 +
 
 +
=Pushing a branch onto another Git server=
 +
You may want to synchronize another GIT server.
 +
To synchronize push to another server, this is how to proceed.
 +
With Eclipse:
 +
 
 +
*Go onto Git clone view and add a remote with a name, choose "Configure push" and enter URL. For example, for name "sourceforge" and URL "ssh://yoursourceforgelogin@git.code.sf.net/p/dolibarr/code"
 +
*Just validate, a first push will be done automatically.
 +
*To force sync, run
 +
 
 +
<source lang="bash">
 +
git push sourceforge develop
 +
git push --tags sourceforge develop
 +
</source>
 +
 
 +
=Statistics=
 +
With GIT Command Line interface:
 +
 
 +
To count number of changes developers have made between a version x and y:
 +
 
 +
*First, search commit id of tags you want to compare
 +
 
 +
To find id_start (common commit id between 2 versions/tags)
 +
<source lang="bash">
 +
git merge-base refs/tags/3.3.0 origin/3.4
 +
or
 +
git merge-base 3.7 origin/develop
 +
</source>
 +
To find id_end, choose among
 +
<source lang="bash">
 +
git show-ref
 +
</source>
 +
Choose a value for id_start and id_end
 +
Note: id_end can be HEAD.
 +
 
 +
*Then run git log to have list of all changes from last common commit to last commit
 +
 
 +
<source lang="bash">
 +
git log id_start..id_end
 +
</source>
 +
 
 +
*To get total number of added/deleted lines:
 +
 
 +
<source lang="bash">
 +
git log --ancestry-path --numstat --pretty="%H" id_start..id_end | awk 'NF==3 {plus+=$1; minus+=$2} END {printf("+%d, -%d\n", plus, minus)}'
 +
</source>
 +
 
 +
 
 +
To count number of changes finally between a version x and y (it differs from previous count because in previous count, a change can be done 2 times at two different moment to change differently. With second method, you count changes finally found if changes were ok at first try).
 +
 
 +
*Use same method than previously but instead of running git log, run git diff.
 +
 
 +
<source lang="bash">
 +
git diff -b -M --numstat --pretty="%H" id_start..id_end | awk 'NF==3 {plus+=$1; minus+=$2} END {printf("+%d, -%d\n", plus, minus)}'
 +
</source>
   −
This method allows you to get CVS version of main development branch (called HEAD). This operation consist to get last version of Dolibarr files that are packaged each night into a zip file.
  −
For this, go on page with [http://www.dolibarr.org/downloads/cat_view/64-development-version last CVS version of the day].
     −
New files will overwrite old ones.
+
More information in GIT usage is available [http://wiki.eclipse.org/EGit/User_Guide here].
−
The inconvenient of this method is that you must download and uncompress again all archive file to get updates.
+
[[Category:Development]]
Retrieved from "https://wiki.dolibarr.org/index.php?title=Special:MobileDiff/22941...62926"