Developing FreeCAD with GitKraken

FreeCAD uses Git to manage its source code. This document is a cursory introduction to GitKraken, a graphical user interface to Git. GitKraken is proprietary software that is free to use for non-commercial use; you don't need GitKraken to develop code for FreeCAD but many developers like it, and find it useful to manage their development. FreeCAD doesn't endorse GitKraken but we hope a guide like this one shows users how easy it is to set up the development environment and encourages more people to contribute.

For more information on general Git usage from the command line see Source code management, and the online Pro Git book. To compile FreeCAD see Compiling.

Introduction
Git is a powerful revision control system commonly used to track computer code development. Although it is a complex system, you usually only need some background information on how it works, and to know a few terminal commands. A graphical user interface (GUI) eases the learning curve. GitKraken is a proprietary program that is free to use for non-commercial use that runs on the Electron framework, which means it is cross platform and can be used the same in Linux, MacOS, and Windows.

Setting up Git development
There are different ways to download GitKraken depending on your operating system. In Linux distributions, sometimes you can get it from the package manager.

  Download GitKraken  In your web browser go to: https://github.com/FreeCAD/FreeCAD  Click the Fork button. This will clone the repository to your own account. In other words the URL to access your fork of FreeCAD is: https://github.com/GITUBUSERNAME/FreeCAD.git   Open GitKraken and go to   GitKraken will now git clone your personal repository.

Please read the difference between origin vs. upstream remote repository. Essentially, your fork of FreeCAD is the repository, while the official FreeCAD repository is. You now need to set the upstream accordingly.  Go to, or press the + combination in your keyboard  Enter the following to set up your remote repository. git remote add upstream https://github.com/FreeCAD/FreeCAD.git   Now check the remote branches you have set: git remote -v </li>  You should see something like this in the terminal: origin	https://github.com/foobar/FreeCAD (fetch) origin	https://github.com/foobar/FreeCAD (push) upstream	https://github.com/FreeCAD/FreeCAD.git (fetch) upstream	https://github.com/FreeCAD/FreeCAD.git (push) </li>  Switch back to GitKraken interface.</li>  On the left side of the screen you will see a sidebar with a section labeled Local; double click on the branch so you switch to it. In the command line, this is equivalent to git checkout master </li>  Click on the Push icon on the top right side of the interface. This will push your Local master to your Remote origin master</li> </ol>

Deciphering the GitKraken interface
For more information consult the GitKraken Getting started guide.



In the image, the remote the Local master and Remote origin master branches are three commits behind the Remote upstream master, that is, the official FreeCAD source code. This is indicated by the icons being three steps behind in the chain that represents the commit history of the master branch. See Rebasing to update the branches that are behind.

Rebasing

 * Checkout the Local master branch by double clicking on it
 * Move the mouse to the last upstream commit, right click, and choose Rebase master on upstream/master
 * Now press the Push button . This pushes from your Local master to the Remote origin master.



Branches
Branches are a feature that makes Git powerful compared to other revision systems. Branches aren't complete forks, but rather define snapshots where a version of the code starts diverging from the master branch. Whenever you want to modify the FreeCAD code, first create a branch, then make changes, and then merge your commits back to the master branch. With Git it is simple to create, merge and delete branches when you no longer need them. Please read Branching and Merging to understand more about this process in GitKraken.


 * 1) Make sure you currently have the master branch active (double click on it, ). In GitKraken the Local master branch should be highlighted in green.
 * 2) Click the Branch button to create a new branch and enter its new name.

Making pull requests
Gitkraken saves you some clicks to easily create pull requests (PRs) through its UI instead of you having to go to your FreeCAD fork on GitHub (AKA origin or ) and using the GitHub interface to submit the PR. This is pretty slick. To summarize the process, once you've modified your branch and ready to have it reviewed, you need to push it to your Github fork (origin) and from there make a pull request to (upstream).

Step by step instructions on how to make a PR in Gitkraken:

Gitkraken will then push your local branch to your GitHub account and then automagically open a Pull Request dialog window that asks you what repository and branch you want to submit your PR to.
 * Find you local branch on the interface and make sure it's active (doubleclick on your branch name)
 * Right click the branch name and find the option to Find <your-branch-name> and start a pull request


 * Gitkraken will ask you what you want to call this branch on your origin remote by prompting you with a dialog box at the top of the UI. Choose the same branch name which should be the default.


 * Gitkraken then opens up another dialog box asking where you want to submit (push) your remote origin branch to? Easy! We want to send it to the FreeCAD Github repository (AKA upstream or FreeCAD/FreeCAD) and to the master branch.

Read the official documentation on the Gitkraken site on how to make a PR link

Resolving merge conflicts

 * GitKraken compatible 3rd party external merge tools
 * If none of the above options in GitKraken work for you, it's possible to specify 3rd party git merge tools within your ~/.gitconfig

Squashing commits
Squashing is when you have several commits you want to condense down in to one commit. From the GitKraken manual: Squashing is available for commits that meet the following requirements: If all these conditions are met, the Squash option appears when you right click the commit node. See screencast at: https://support.gitkraken.com/img/documentation/working-with-files/commits/squash.gif
 * Selection contains more than one commit
 * The youngest commit (by commit date) is also the current HEAD commit
 * Genealogically consecutive
 * Chronologically consecutive
 * The oldest commit in the list has a parent

Follow other FreeCADers branches
Remotes are forked repositories of FreeCAD/FreeCAD by fellow FreeCADers. You can use Gitkraken to follow how FreeCAD devs code and commit to their own branches before they send git Pull Requests to the main FC repo. Here is how you can follow other users: Whenever new commits are made or branches are rebased by said user you will see it represented in the gui.
 * 1) In the left side panel there is a Remotes category. Press the +
 * 2) A dialogue will come up that can give you the option to choose which remote you want to follow. Recommended remotes are: wmayer, yorikvanhavre, ickby, sliptonic, kkremitzki etc....
 * 3) Choose 'Add Remote'