Developing FreeCAD with GitKraken: Difference between revisions

From FreeCAD Documentation
(Separating headers from content, removing needless <hr /> html tags, removing images and code from translation, changing Pull Request to pull request as per discussion on not using uppercase in new wiki page names)
mNo edit summary
Line 9: Line 9:


== Setting up Git development ==
== Setting up Git development ==

<ol>
<ol>
<li> Download GitKraken (There are different ways to download GitKraken depending on your OS. I use an Arch Linux based distro called Manjaro and added it through my package manager)</li>
<li> Download GitKraken (There are different ways to download GitKraken depending on your OS. I use an Arch Linux based distro called Manjaro and added it through my package manager)</li>

Revision as of 19:01, 15 December 2018

Other languages:
Please Read

This guide is not written to teach users how to use git in its totality, far from it. Git is super handy tool with a lot of functionality that goes way beyond the scope of this intro. This is just a cursory introduction highlighting on how to work with Git in a GUI environment. It also serves as a means to encourage FreeCAD users to contribute to FreeCAD. This tutorial uses GitKraken, proprietary software that is free to use for non-commercial use.


Introduction

Want to contribute to FreeCAD source code but don't know how to use the Git revision system? Git is very powerful and a bit complex... good thing you only need to understand some rudimentary structural theory of how it works and half a dozen of its commands to get by! Even better, you can use a GUI to work with git as a method of understanding it (at least for some) which may make it much less intimidating a learning curve. This is where Gitkraken may work for you. Gitkraken is a proprietary program free to use for non-commercial use that runs on Electron, a cross platform framework (Linux, MacOS, Windows).

Setting up Git development

  1. Download GitKraken (There are different ways to download GitKraken depending on your OS. I use an Arch Linux based distro called Manjaro and added it through my package manager)
  2. In your web browser go to: https://github.com/FreeCAD/FreeCAD
  3. Click the Fork button. This will clone the FreeCAD/FreeCAD repo to your own account. In other words the URL to access your fork of FreeCAD is:
    https://github.com/GITUBUSERNAME/FreeCAD.git
  4. Open GitKraken and go to File → Clone Repo
  5. GitKraken will now git clone your repository
    • Now an important point: Please read the difference between origin vs. upstream remote repos. Essentially your fork of FreeCAD is the origin repo. The official FreeCAD Git repo FreeCAD/FreeCAD is your upstream. You now need to set the upstream repo as FreeCAD.
  6. Go to File → Open Terminal (or press the Alt+T keyboard combo)
  7. Enter the following to set up your upstream remote repo
    git remote add upstream https://github.com/FreeCAD/FreeCAD.git
  8. Now check what remote branches you have set by typing:
    git remote -v
  9. 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)
  10. Switch back to GitKraken interface.
  11. On the left side of the screen you will see a sidebar with a section labled Local double click on the master branch (this will make sure you're on the master branch AKA
    git checkout master
  12. Click on the Push icon on the top right side of the interface. This will push your Local master to your Remote origin master

Deciphering the GitKraken interface

For more in-depth understanding of the GitKraken interface checkout the Getting Started Guide.

Local = Your local machine
Local master Your local branch of the FreeCAD master branch (symbolized by Blue line in Screenshot).
Note: the branch is highlighted in green which means that you currently have the master branch 'checked-out'
Local <branch-name> Any other branches on your local machine. In the screenshot you can see an example called editor-fixes and editor-fixes-typos
Remote = Remote GitHub repos
Remote upstream Official FreeCAD repo (AKA FreeCAD/FreeCAD) (symbolized by Green line in Screenshot)
Remote origin Your fork of FreeCAD/FreeCAD (AKA github.com/YourGitHubUsername/FreeCAD) (symbolized by Red line in Screenshot)

Notice

In the above screenshot Remote origin master and Local master are a few commits behind Remote upstream master (in other words you can see the that upstream master branch is all the way at the top of the screen and the other branches are a 3 commits behind it). You can remedy this by Rebasing which essentially will update the branches that are behind.


Rebasing

  • Checkout the Local Master branch by double clicking on it (this is the equivalent of typing git branch master in the terminal)
  • Move the mouse to the where latest Upstream commit is, right click mouse and choose Rebase master on upstream/master (this will pull down the Upstream changes in to your Local master)
  • Move the mouse and press the Push button. GitKraken (This pushes from your 'Local master' to 'Remote Origin master')

Now all your repos are in sync!

Branches

Branches make git beautiful. A branch is (not technically speaking) a copy or fork of the source code split off from itself. If you want to edit something in the code base your first move is to make branch. You work in that branch, making modifications to it until you are complete. Then when you're ready you make a pull request to merge your revisions back in to the main branch. Read up on the Gitkraken documentation on Branching to understand more about it. In general it's easy to create a branch on Gitkraken. Note: develop the habit to always open a new branch before you start to code, this can help you avoid making mistakes (that are reversible but nonetheless time-consuming).

  1. Make sure you currently have the master branch 'checked-out'. In the above section: Deciphering the GitKraken interface, look in the left sidebar in the Local sub-menu how 'Master' is highlighted in green. This means that you're currently in the Master branch. If you're on another branch, then double click on the Local Master branch which will checkout the Master branch. The CLI equivalent of this is git branch -v and git checkout master
  2. Click the 'Branch' icon button at the top of the UI and you will be prompted to give a name to your branch.
  3. The result is that you've made a branch off of the Master branch. The CLI equivalent of all this is if you ran git checkout -b <name-of-your-branch>

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 github.com/GITUBUSERNAME/FreeCAD.git) 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:

  • 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 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.

  • 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

Notice

GitKraken has a special merge conflict tool that is only accessible in the GitKraken Pro version. But there are workarounds to use external git merge 3rd party tools


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:

  • 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

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

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:

  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'

Whenever new commits are made or branches are rebased by said user you will see it represented in the gui.