{{man tip|The development source code of Gramps is stored in the Git repository at SourceForgeGitHub.|https://github.com/gramps-project/gramps/}}The Gramps project uses the [https://en.wikipedia.org/wiki/Git Git program] to help synchronize changes to source code from various developers, tracking changes, managing releases, etc. You are probably here because you want to do one of two things with Git; either:* Download the latest maintenance source version or the development version, or else * [[Brief_introduction_to_Git#Send_your_contribution_without_rights_to_push|Submit a Pull Request (PR)]] with the changes (if you don't have write access) or upload your changes (if you have write access to the repository).

;[http://git.code.sf.net/p/gramps/source/ http://git.code.sf.net/p/gramps/source/]. == Install Git on your system == This helps synchronizing changes from various developers, tracking changes, managing releases, etc. If you are reading this, you probably want to do one of two things with Install Git: either download the latest source or the development version, or else upload your changes (if you have write access to the repository) or and then [[Brief_introduction_to_SVN#Making_a_patchfileConfigure_Git_settings|make a patchfileconfigure your Git settings]] (if you don't have write access). == Obtaining a copy of the Gramps repository =Linux=== Install Git on your system.* Debian/Ubuntu: <code>sudo apt-get install git</code>

Git includes your name and email address in commits===Apple Mac OS X===* '''Mac OS X (Intel)''': Download git from here https://git-scm. To configure them, use com/download/mac* '''Mac OS X (PPC)''': Although the following commandsgit download is called '<code>[https: //sourceforge.net/projects/git-osx-installer/files/ git config -2.xx.x-intel-universal-global usermavericks.name "John Smith" dmg]</code>', implying that this is a universal binary, in fact only the installer is universal, the binary to be installed in actually intel only. On a PPC you will need to build git manually. Follow the instructions here: http://jnorthr.wordpress.com/2013/03/29/building-a-git config -client-global user1-8-2-on-apple-imac-ppc-osx-10-5-8/.email john@exampleI think you will also need some additional tools like 'msgfmt'. I don't think this is installed by the Apple development tool Xcode, but fortunately I have it either via fink which I installed some time ago, or via MacPorts which I installed more recently.com

: Mac OS X (PPC) Eclipse. If you are using Eclipse on a PPC, then there may be missing components for installing the latest version of EGit, depending on your version of Eclipse. If you have the Helios version of Eclipse, then you will not be able to install the latest EGit because you will get ''requires 'org.eclipse.team.core 3.6.100' but it could not be found''. Installing EGit version 2.0 from http://download.eclipse.org/egit/updates-2.0 should work if you uncheck the EGit Import Support feature when selecting what to install. You should see will obviously lose the downloading progress reported in your terminalImport Support feature. See [http://stackoverflow.com/questions/15281273/dependency-fail-installing-egit-on-eclipse-indigo here]. You will probably need to do ''git config core.filemode false'' to get round [https://bugs.eclipse.org/bugs/show_bug.cgi?id=307560 this bug] as suggested [http://stackoverflow.com/questions/1257592/how-do-i-remove-files-saying-old-mode-100755-new-mode-100644-from-unstaged-cha here].

If you have a SourceForge account, use ssh instead:<code> git clone <nowiki>sshEclipse then will need to locally ignore the Eclipse files as suggested at 5.2.2 [http://<username>@git.codewww.sfvogella.netcom/ptutorials/grampsEclipseGit/source</nowiki> Gramps</code>article.html#d186251e250 here].

You will need a [http: cd ~//sourceforge touch .gitignore echo ".metadata" >> .gitignore echo ".project" >> .gitignore echo ".pydevproject" >> .net/p/forge/documentation/SSH%20Keys/ SSH Key] in order to authenticate using this methodgitignore echo "windows" >> .gitignore

== Basic Work Flow = Configure Git settings ===

The basic work flow after you've checked out Git includes your name and email address in commits. To configure them, use the repository is update, develop, commit, update again, pushfollowing commands: git config --global user.name "John Smith"To update the current branch, run git config --global user.email [email protected]

Git will automatically convert line endings for you. Use the following settings: git pull config --rebaseglobal core.autocrlf true # Windows git config --global core.autocrlf input # Linux/Mac

As a general rule Git can invoke your editor for commit messages, rebasing etc. git config --global core.editor "'C:\Program Files (x86)\Notepad++\notepad++.exe'always'' use <tt>-multiInst -notabbar -nosession -noPlugin" # Windows git pull config --rebase</tt> to avoid creating unnecessary merge commits. Note that one must have no uncommitted edits when running <tt>git pull</tt>global core.editor "vim" # Linux

To commit your changes locally, use == Obtaining a copy of the following command:Gramps repository ==

The description below is for a single working folder at <code>~/Gramps</code>. If you are working on a plugin, the folder name should be 'addons-source' at the <nowiki>https://github.com/gramps-project/addons-source.git commit</nowiki>

Which will bring up the default $EDITOR to create ===Without a commit message. If you are fixing GitHub account===To obtain a bugcopy of the Gramps repository, type the following in the first command line of the commit message should be the bug number and title, otherwise if you '''don't have a brief statement of purposeGitHub account''': git clone <nowiki>https://github. Skip a line and describe what you didcom/gramps-project/gramps.git</nowiki> Gramps

* All developers You should read Gramps [[Committing policies]]see the downloading progress reported in your terminal.

===With a GitHub account===If the commit is you have a minor change that can be described entirely in the subjectGitHub account, you can use ssh instead use: git clone <nowiki>[email protected]:gramps-project/gramps.git</nowiki> Gramps

git commit You will need a [https://help.github.com/articles/generating-am "message describing ssh-keys/ SSH Key] in order to authenticate using this method. '''Before you accept any host keys, make sure you [https://help.github.com/articles/what-are-github-s-ssh-key-fingerprints/ verify the nature SSH fingerprint]''' of the change"github.com.

Try to keep You can check your commits digestible and understandableconnection by: ssh -T git@github. A large changeset can be broken into several commits that "tell a story" about how the changeset moves the program from its old behavior to its new onecomwhich should return: Hi <name>! You've successfully authenticated, but GitHub does not provide shell access.

To push your changes to Once the Gramps repositoryclone is complete, you need to have cloned a local copy of the Gramps source code with ssh, and have push access Git configured to use this as the Gramps repository (the Gramps admins 'origin'. You can give you see this, [[Contact|Brian Matherly or Benny Malengier]]by: git remote -vwhich should return: origin <nowiki>https://github.com/gramps-project/gramps.git</nowiki> (fetch) origin <nowiki>https://github. First update again to make sure that you can fastcom/gramps-forward the repository, then project/gramps.git</nowiki> (push:)

If you have 'push rights' to the Gramps repository, (members of the 'developers' group have this), then you are good to go. git pull --rebaseIf not, then you will have to establish your own github account and use that for a place to publish your contributions. git pushThis is not needed until (or unless) you desire to contribute more than a simple patch to Gramps.

Since uploading You should sign up for an account on https://github.com. GitHub is a potentially dangerous operation, most people do not obtain write access free to the git repositoryuse for public and open source projects like Gramps. In this case, You should create a new bug repository on the [httpgithub that can receive your pushed contributions. The examples below assume that is also called 'gramps'. See https://bugshelp.grampsgithub.com/articles/creating-project.org bug tracker] and attach a patch to it. See the [[Brief_introduction_to_Git#Making_a_patchfile|make a patchfile]] section for details.-new-repository/

If someone else has made changes Once you have that interfere with yoursset up, you will get should set up a conflict error when you pullsecond remote tied to your local repository. You will have My personal arrangement is to change the name of the original tie to the remote Gramps github repository to resolve that conflict 'upstream' and remake the tie to my personal github repository 'origin': git remote set-url --push upstream <nowiki>cannot_push</nowiki> git remote set-url --fetch upstream <nowiki>https://github.com/gramps-commit (you can use project/gramps.git</nowiki> git remote set-url --push origin <nowiki>https://github.com/my-name/gramps.git<tt/nowiki> git commit remote set-url --fetch origin <nowiki>https://github.com/my-amendname/gramps.git</ttnowiki> if it affects only When done, you can check the last ''unpushed'' commitresults: git remote -vwhich should return: origin <nowiki>https://github.com/my-name/gramps.git</nowiki> (fetch) before origin <nowiki>https://github.com/my-name/gramps.git will </nowiki> (push successfully) upstream <nowiki>https://github.com/gramps-project/gramps.git</nowiki> (fetch) upstream <nowiki>cannot_push</nowiki> (push)

:Also see: == Branches [[Getting started ==Branches are the particular group of code sources associated with a Gramps Trunk]]version, enhancement, bug fix etc.When making changes to Gramps, it is important to understand where you are starting from (which version of Gramps) and what you are trying to do.

=== Types of branches ===

* ''master'' - There is only one ''master'' branch. All new feature and most bug-fix development happens in the ''master'' branch. New releases never come from the ''master'' branch.

* ''maintenance'' - There are many maintenance branches, though usually only one or two are active. A maintenance branch is created from the ''master'' branch when all the features for a release are complete. New features are not committed to maintenance branches. Releases only come from active maintenance branches; a branch is no longer active when no further releases are planned for it. Inactive branches should not have any changes committed to them. The purpose of maintenance branches is to allow the line of code to stabilize while new features are added in the ''master'' branch. In order to prevent regressions (fixed bugs reoccurring in later releases), it the current maintenance branch is a "best practice" to fix bugs on regularly merged into the ''master '' branch and then to backport them to the current maintenance branches.

There are several versions of the Gramps source code in Git. The development branch for small changes and bug fixes is ''maintenance/gramps{{stable_branch}}gramps51''.

By default, the remote server you cloned the Gramps repository from is called ''origin'', unless you changed the setup as described above. In that case it is ''upstream''.

git remote show remote originupstream

git checkout -b gramps40 origingramps51 upstream/maintenance/gramps40gramps51 {{man warn|1=Warning|2=This sets the name of the local branch to "gramps51" (not "maintenance/gramps51"). This may cause problems when you come to "push" your changes back to the server, depending on the "push.default" configuration settings (see below). You can change the name of the local branch by "git branch -m old new" i.e. git branch -m gramps51 maintenance/gramps51}}

To look at any stable release version, and create a new local branch off of it, type:  git checkout <tag> -b <new_local_branch_name> The following configuration option simplifies pushing a branch back to the server:  git config --global push.default upstream You can then use:  git push {{man warn|1=Warning|2=This will push committed changes from '''all''' local branches, not just the one that is currently checked-out. If you want to ensure that only one branch is pushed, then use: git push origin gramps51:maintenance/gramps51}} While it is certainly possible to do your contributions directly in the particular branch you start from, whether it be 'master' 'maintenance/gramps51' or something else, it is more usual to create a branch of your own for each significant change. That way you can work on each separately, and change from one to the other without getting the changes intermixed. For example if you are creating a new report you might want to call the branch 'gen-report'. If you are basing this off of the 'master' branch, then you would start by: git checkout master # this ensures your work is based on master branch git checkout -b gen-report # this creates a new branch 'gen-report' based on master but separate.You can create many such branches and switch between them with 'git checkout <yourbranch>' as long as you save your work via 'commit' (described below) before making the switch. ===Alternative approach=== Where for bugs? For an alternative approach see [[Brief_introduction_to_Git#Multiple_Working_Folders|Multiple Working Folders]]. ==Basic Work Flow == The basic work flow after you've checked out the repository is update, develop, commit, update again, push.To update the current checked out Gramps branch (master in this case) from Gramps github, run  git pull --rebase upstream masterIf you are working on a branch of your own creation ('mybranch'), based off of master, and currently have 'mybranch' checked out, I prefer to run git fetch upstream # copies the latest stuff from Gramps on github git rebase upstream/master # shift my work to be 'on top' of other peoples work As a general rule ''always'' use <tt>git pull --rebase</tt> to avoid creating unnecessary merge commits. Note that one must have no uncommitted edits on that branch when running <tt>git pull</tt>. The differences between "git pull" and git pull --rebase" is explained well [http://stackoverflow.com/a/3357174/2615612 here]. You make your changes next with your preferred editor, debugging the code locally. To see exactly what you have changed from the original (master in this case): git diff masterTo see changes since your last commit: git diff To review your change files before a commit, type:  git status To stage and commit your changes locally, use the following commands:  git add * # the '*' adds every changed file to the stage, or you can specify a single file git commit Which will bring up the default $EDITOR (or the editor you setup with 'git config' above) to create a commit message. If you are fixing a bug, the first line of the commit message should be the bug number and title, otherwise a brief statement of purpose. Skip a line and describe what you did. * All developers should read Gramps [[Committing policies]] If the commit is a minor change that can be described entirely in the subject, you can instead use:  git commit -am "message describing the nature of the change" Try to keep your commits digestible and understandable. A large changeset can be broken into several commits that "tell a story" about how the changeset moves the program from its old behavior to its new one. To push your changes to the Gramps repository, you need to have cloned the Gramps source code with ssh, and have push access to the Gramps repository (the Gramps admins can give you this, [[Contact|Brian Matherly or Nick Hall]]). If you don't have push access continue in the next section below. First update again to make sure that you can fast-forward the repository, then push:  git pull --rebase git push If someone else has made changes that interfere with yours, you will get a conflict error when you pull. You will have to resolve that conflict and re-commit (you can use <tt>git commit --amend</tt> if it affects only the last ''unpushed'' commit) before git will push successfully. Since uploading is a potentially dangerous operation, most people do not obtain write access to the git repository. You can use one of two approaches to this, either make a 'patch' (useful for small bug fixes), or you can make a 'Pull Request' (PR). See the [[Brief_introduction_to_Git#Making_a_patchfile|make a patchfile]] or [[Brief_introduction_to_Git#Making_a_PR|Making a PR]] sections for details. :Also see: [[Getting started with Gramps master]].

If you do not have push access to the repository, you can make a A patchfile with your changes. This is a text file with your changes which can then be sent by email to somebody, or posted/uploaded to the bug tracker (against a bug you are fixing or a feature request which you are solving for instance), etc...

# Always do '<code>git pull' --rebase</code> before pushing changes to the server. If necessary get advice about handling conflicts.# Always do '<code>git status' </code> and look for staged files that are unexpected or unintended. This is a *very important* sanity check.

* avoid Avoid grouping unrelated changes; better to divide into separate commits for the following reasons: a better log entry; easier troubleshooting/reverting. (and probably more).

* similar Similar to above, it may be better to make small incremental changes than one big one (if possible). Interim changes should not introduce breakage, of course. For instance, if you change code in gramps/ and do associated translation changes in po/, you might want to commit the changes in po/ in a commit following the commit(s) with the changes in gramps/.

=== Browse Git === An alternative to the command line tools to view the Git repository is the [https://github.com/gramps-project/gramps online interface]. == Multiple Working Folders =={{man note|Multiple Working Folders|This type of setup is uncommon.}}Using a single working folder as described above entails context switching when developing across multiple branches. For example:* develop and test changes on the gramps41 branch,* commit or stash the changes,* clean to remove untracked files created by the development process,* checkout the master 'branch',* build (python setup.py build),* cherry pick the changes from the gramps41 branch into the master 'branch',* test and if necessary develop the changes to master,* commit or stash the changes. If the changes are all OK, then they can pushed to the GitHub repository. An alternative is to clone the GitHub repository for each branch, but although git saves local disk space by using hard links for locally cloned repositories, keeping the local repositories in sync is complex. The problem is well explained [https://www.finik.net/2010/10/24/multiple-working-folders-with-single-git-repository/ here] as is the solution, which is to create copies of the working directories only.  This can be done using either the builtin <code>git worktree</code> command since Git 2.5.0 or by a script that is in the git 'contrib' directory [http://nuclearsquid.com/writings/git-new-workdir/ git-new-workdir] for older versions of Git. Note that <code>git worktree</code> supports windows out of the box. ===git-new-workdir=== Assuming that the directory structure would be: ~ +-Gramps +-repository +-.git +- etc +-gramps34 +-gramps40 +-gramps41 +-gramps42 +-gramps50 +-master The approach would be:* clone from the GitHub repository:

An alternative mkdir Gramps cd Gramps mkdir repository cd repository git clone [email protected]:gramps-project/gramps.git * then create the various working copies:  # git-new-workdir path/to /repository path/to/new/workingdir branch git-new-workdir ~/Gramps/repository ~/Gramps/gramps34 maintenance/gramps34 git-new-workdir ~/Gramps/repository ~/Gramps/gramps40 maintenance/gramps40 git-new-workdir ~/Gramps/repository ~/Gramps/gramps41 maintenance/gramps41 git-new-workdir ~/Gramps/repository ~/Gramps/gramps42 maintenance/gramps42 git-new-workdir ~/Gramps/repository ~/Gramps/gramps50 maintenance/gramps50 git-new-workdir ~/Gramps/repository ~/Gramps/master master You will then need to build the command line tools source, but this only needs to view be done once, and the Git repository 'clean' step is not needed. See [[Getting_started_with_Gramps_development#Run_Gramps_from_the_source| Run from source]] and [[Running_a_development_version_of_Gramps| running]] which describes the process for 'gramps 3.4 and before' as well as after. For example:  cd ~/Gramps/gramps41 python setup.py build ===git worktree=== {{stub}}<!--test and expand this--> Although from Git 2.5 (Q2 2015) a replacement for contrib/workdir/git-new-workdir was [http://stackoverflow.com/questions/6270193/multiple-working-directories-with-git/30185564#30185564 builtin] to git, it is recommended that you use the 'recipe' above instead of the builtin, in order to ensure that the repository is in the right place, and in view of the warning below.code  WARNING.sf.netUsing the builtin 'git worktree' may not be supported by Eclipse (as at Dec 2017), see [https:/p/grampsbugs.eclipse.org/sourcebugs/ online interfaceshow_bug.cgi?id=477475 Bug 477475 - git 2.5 worktree support].

*[https://githelp.wikigithub.kernel.orgcom/articles/index.phpgenerating-ssh-keys/GitSvnCrashCourse GitSvnCrashCourseGitHub SSH Keys]*[httphttps://sourceforgehelp.github.netcom/particles/forge/documentationwhat-are-github-s-ssh-key-fingerprints/GitHub SSH%20Keys/ SourceForge SSH KeysKey Fingerprints]