Source code management

Introduction
The main source code management tool for the FreeCAD project is Git, which can be easily installed in most operating systems from a package manager or directly from Git's website. You are advised to become familiar with Git before working with the FreeCAD source code directly. Visit the Git documentation page for the reference manual, as well as the Pro Git book to learn to use the system in a general way. The present document focuses on the use of Git for FreeCAD development. Compiling FreeCAD is described in Compiling.

While Git is primarily a terminal application, there are many graphical clients for it which facilitate working with branches, applying patches, and submitting pull requests to a master branch. Examples include gitk (the first graphical interface developed), gitg (Gnome), qgit (Qt), tig (Ncurses), git-cola, and GitKraken (proprietary). Please see Developing FreeCAD with GitKraken for a cursory introduction to this tool.

Note: if any of this is starting to make you dizzy, there is a very good non-technical series on how to use git and Github called 'Git and Github for Poets'

Source code access
Everybody can access and get a copy of the FreeCAD source code, but only the FreeCAD project managers have write access to it. You can get a copy of the code, study it and modify it as you wish, but if you want your changes to be included in the official source code, you need to perform a "pull request" against the master repository so that your modifications can be reviewed by the managers. This style of development is known as the Dictator and lieutenants workflow, as the core developers (dictators) and trusted developers (lieutenants) filter the code that is submitted by independent developers and users.

If your source code changes are significant, you are advised to explain them in the pull request section of the FreeCAD forum.



Official GitHub repository
The FreeCAD source code is hosted in Github, https://github.com/FreeCAD/FreeCAD

In order to contribute code, you need to have a GitHub account.

In the past, the source code was hosted as an SVN repository, https://free-cad.svn.sourceforge.net/svnroot/free-cad. This was moved to GitHub on 2011 October 10th, with commit 120ca87015.

Therefore, there are many changes that were made before this time which are not recorded in the modern Git commit history.

Setting your Git username
Developers should commit code to their personal repository using their GitHub username. If that is not already set globally, you can set it locally for the current Git repository like this:

Where represents your full name or nickname, used to identify the author of a particular commit, and  indicates the name of your account on GitHub.

Remote repositories
Please read What is the difference between origin and upstream on GitHub? (Stackoverflow) to help you understand the difference between and  in the context of Git. This section explains how to set the correct repositories for development. Essentially:
 * is your personal fork of the official FreeCAD repository, that is, https://github.com/GITHUB_USERNAME/FreeCAD
 * is the official FreeCAD repository, that is, https://github.com/FreeCAD/FreeCAD

This distinction is important, as you should write code in your own copy of the repository first, before pushing those changes to the official repository.

Based on the above, there are two ways to setup your Git development environment:
 * 1st Method: fork on GitHub and clone your fork locally
 * 2nd Method: clone FreeCAD directly to your local machine, and adjust the remote servers

We recommend the 1st method because it's one step faster.

1st Method: Fork on GitHub and clone your fork locally
First you will fork the FreeCAD repository in GitHub, then clone this personal fork to your computer, and finally set the repository.
 * Log in to your GitHub account.
 * Go to the official FreeCAD repository: https://github.com/FreeCAD/FreeCAD
 * In the top right of the page press the "Fork" button. This will create a personal copy of the FreeCAD repository under your GitHub username:
 * On your machine, clone your newly created FreeCAD fork. It will be created inside a directory.


 * Once the download is complete, enter the new source directory and set the repository.


 * Confirm your remote repositories with ; the output should be similar to this


 * Now development can begin.

2nd Method: Clone FreeCAD directly to your local machine
First you will fork the FreeCAD repository in GitHub, however, you will clone the original FreeCAD repository to your local machine, and then alter your remotes via the terminal.
 * Log in to your GitHub account.
 * Go to the official FreeCAD repository: https://github.com/FreeCAD/FreeCAD
 * In the top right of the page press the "Fork" button. This will create a personal copy of the FreeCAD repository under your GitHub username:
 * Clone the original FreeCAD repository. It will be created inside a directory.


 * Once the download is complete, enter the new source directory and set the repository.


 * Then set up the repository.


 * Confirm your remote repositories with ; the output should be similar to this


 * Now development can begin.

If for some reason the remote repositories exist but point to the wrong address, you can remedy the situation by renaming the remote repository's name. For example, should point to your personal fork; if it is pointing to the original FreeCAD repository, change the name of this remote to, and manually add the  repository.

You can also show more information with the keyword.

Branching
Instead of working on the master version of the code, best practices with Git recommend creating a new branch whenever you want to work on a new feature. Branches are inexpensive, they don't copy the entire source tree, but merely create a point in time on top of which you will write code; thus branches help keep work in progress separate from the main code.

Using a new branch is done in two steps, first your create the branch, and then you switch to it:

Alternatively, perform both steps with a single instruction:

Now you can change branches with whenever you need to work on them. To see the branches in your project and the current branch, use the operation alone, or add  or  for more information:

After you've made changes and committed those changes use the operation with the following options to visualize the branches

Committing
Once you are inside a new branch, edit the source files that you want with a text editor. To see which files were modified use the and  operations; when you are satisfied with the modifications, save the changes with the  operation:

Unlike SVN, you need to specifically tell which files to commit; use the option to save changes in all files that were altered. Your text editor, for example, or, will open to allow you to write a commit message.

Alternatively add the message in the commit itself:

If you create new files or directories, you must use the operation first to add them to the local repository before committing the changes.

Where can be any directory or file.

Writing good commit messages
You should try to work in small steps, that is, commit often, after a small addition in your code. If you cannot summarize your changes in one sentence, then it has probably been too long since you made a commit.

For big changes, it is important that you have helpful and useful descriptions of your work. FreeCAD has adopted a format mentioned in the Pro Git book, which consists of a short message, and then a larger descriptive paragraph.

If you are doing a lot of related work in a branch, you should make many small commits (see a forum post). When you want to merge those changes into the master branch, you should issue

to see the individual commit messages. Then you can write a high quality message when performing a merge.

When you merge to master use the option and commit with your quality commit message. This will allow you to be very liberal with your commits and help to provide a good level of detail in commit messages without so many distinct descriptions.

Squashing commits
Squashing refers to the process of combining various consecutive commits into one. This may be desirable if you made many small commits that you want to present as a single commit, for example, when changing a single variable, correcting spelling mistakes, and adjusting the spacing of the code. You should squash only small commits to a single file; big changes to the code across multiple files should contain the full commit history.

With you can see many commits in sequence, with the newest commit on top. In this example, starting from "feature A" many commits are made to implement "feature B"; we would like to squash all commits belonging to "feature B" into one.

Use the operation with the  or  option to select various commits and squash them. Use the hash of the commit just before the first one that you want to squash, in this case the one corresponding to "feature A".

The command line editor, like or, will open to show you the commits again, now with the older commit on top. Before each commit, the word will be shown. Delete the word, and write the word or just the letter  instead, with the exception of the first entry; this commit is the oldest one, so all future commits will be squashed into it.

Save the file and close the editor.

The editor will open up again. Now you can add a longer message that describes all changes as if they were a single commit. Save the file and close the editor once more. This will finish combining those commits into one, with the new commit message that you wrote.

You can use again to observe the new commit history. In this case only a single commit for "feature B" will appear, on top of the unmodified commit for "feature A".

Pushing your work to your GitHub repository
The local branches in your computer aren't automatically synchronized with the remote servers that you have specified as or  (see Remote repositories); you have to explicitly push the branches to the remote servers, for which you must have write access. Once you do this, the branches become public, and available for review by other developers.

For FreeCAD, you should push your local branch to the remote repository, that is,. You need to enter your username and password every time you push, unless you have set up Credential caching. Please read Pushing commits to a remote repository for more information.

When you work with a single branch, you may need to interactively rebase, squash, and fix commits many times. In this case, your branch history will not be simple, and you will not be able to push it to the remote repository. You may get a message like the following, saying that it is not possible to do a "fast-forward" push.

In order to finally push your branch to the remote repository you need to "force push" it. This will completely overwrite your remote branch with the actual branch that you have offline.

The regular developer doesn't have write access to the repository https://github.com/FreeCAD/FreeCAD, therefore, you should never push code to this remote server.

Rebasing from upstream
While you work on your own branch, the official FreeCAD code keeps "moving forward" with commits from other developers, and thus starts diverging from the code that you have in your personal fork.

.-A origin/myNewBranch / -o---Z FreeCAD upstream/master

Therefore, when you are ready to merge your branch to the main FreeCAD repository, you must "rebase" your own copy of the repository, so that it is as close as possible to the official repository. See Git Branching - Rebasing for more information.

This will download the code from the branch of the  repository (the official FreeCAD source), and will merge it with your current branch, so that your changes will appear on top of the latest official code. If nobody modified the same files that you did, then the merge will succeed without problems. If some files were changed at the same time by different people, there may be a conflict that needs to be resolved.

.-A' origin/myNewBranch / -o---Z FreeCAD upstream/master

To summarize, you need to be in the appropriate branch, rebase the upstream code, and then proceed with the push.

The operation is equivalent to a  followed by a. When the option is used, instead of doing a simple, it runs the  operation.

Merging the branch (pull request)
Once you have committed your changes locally, rebased your branch from the upstream repository, and pushed your branch online, you can initiate a "pull request". A pull request tells the administrators of the official FreeCAD repository that you want to merge the new code in your branch with the official code.

As soon as you push the code to your repository, GitHub will give you the option of comparing and creating a pull request against the  repository. By pressing you will open an interface that will allow you to pick which repository is the "base", target of the merge, and which is the "head", your additional code. A quick check will be done by the system telling you if there are no conflicts with the files that you modified; if you worked on files that nobody has touched, your branch will be able to merge cleanly. In addition, it will show you a text editor so you can write a message documenting your changes; it will also display the number of commits in your branch, the number of files that were modified, and a view showing you the differences between the "base" and the "head" so that everybody can immediately see your intended modifications.

Click to proceed. A message will appear indicating that some checks need to be done on the code. This is a system that compiles FreeCAD automatically and runs the unit tests. If the tests pass, the pull request will have a better chance of being merged into the main code, otherwise a report will be made indicating the errors encountered. See FreeCAD pull requests.

Some checks haven’t completed yet


 * continuous-integration/travis-ci/pr Pending — The Travis CI build is in progress |Required|

If the tests succeed, you will see a message such as the following

All checks have passed


 * continuous-integration/travis-ci/pr — The Travis CI build passed |Required|

This branch has no conflicts with the base branch Only those with write access to this repository can merge pull requests.

Now you must wait for the administrators to merge your branch; you will be notified when this happens.

If you wish, you may delete the branch that was just merged, or even your entire FreeCAD fork, as your own code is already included at the end of the master branch.

you may continue working on the same branch while you wait for merge approval; if you  again, a second merge commit will be queued in the same pull request, and another automated test will be done. That is, while your merges aren't yet approved by the administrators, you may keep pushing changes to your repository, and this will queue those commits in the same pull request to the  repository. Using a single pull request to queue many individual commits is often desirable for small changes. For big additions to the source code, you should create another branch, develop your features there, and then submit a separate pull request for this branch.

The pull request interface can be used whenever you want to submit code from your own repositories to another repository in GitHub. You can use it to merge code in the opposite direction as well, from other people's branches to your own, or even between your own branches. In the last case, since you own the branches, the merges can be approved by yourself immediately.

Keeping the GitHub repository up to date
Once you've forked FreeCAD, your personal repository exists independently from the original. When the original repository has new commits, GitHub will inform you that your personal repository is behind in number of commits:

In similar way, if you created a development branch with new code, GitHub will inform you that this branch is ahead in number of commits; that is, this branch has changes that haven't been merged into the official FreeCAD repository:

While developing, both cases are possible, as your own branch may lack commits made by other developers, but include new commits by you:

When developing code it is recommended that you rebase the branch in which you are currently working, as that will put your branch always ahead of the FreeCAD master code.

As for your original branch, it will never be automatically updated by GitHub; this is something that you must do yourself. Switch to the branch, then  from  (which performs a  and ), and then push this updated  branch to your remote  repository.

After this is done, GitHub will let you know that your are synchronized with the repository.

Now that your is up to date, you may decide to switch to it, and delete the other branch that you used previously to develop a feature.

To delete the branch in the remote repository, you can use the  operation. Normally, you push a local branch; this creates a remote branch with the same name as your local branch.

However, if you use the notation, the local branch is created in the remote repository under a different name:

Therefore, you can delete the remote branch by pushing an empty local branch:

Now that you only have an up-to-date, you can create a new branch, and repeat the steps of changing files, committing, pushing, submitting a pull request, merging, and updating.

If you don't want to delete your already custom branch, you may force updating it to be equal to the updated ; then you can do whatever you want with it, including adding more commits and pushing it to the remote repository.

Hard resetting a branch like this is usually not needed. In most cases, you want to follow the sequence of creating a new branch, committing changes, pushing those changes, merging the branch, and then deleting the branch.

Searching
Some handy tools to help you find what you're looking for:

Search filenames
Use to search the repository for file that contains a certain string in a filename. The example below will return all instances of the files that contain the 'dxf' in their filenames.

Search for a string
Use to search the repository for file that contains a certain string with the files themselves. The example below will return all instances of the files that contain the 'dxf' within each and every file.

Resolving merge conflicts
Merging branches with, or rebasing your branch with , will occasionally present conflicts, as files may have been modified by another author at the same time. If this happens you should see the changes of both sides, the other author's, and your own, and then make a decision on how to include both sets of changes in the best way possible. This is normally a manual process that cannot be automated; the programmer must understand the code, and decide what code to move, re-write, or drop to solve the conflict.

Once a conflict occurs, a message like this may appear.

If a specialized diff tool is installed and configured for Git, for example, Gnome's Meld, the conflict can be examined and solved by using the operation.

The Meld tool normally displays three columns; the two columns on the sides display the two conflicting files, while the column on the middle displays the new code that will be saved and committed finally. Therefore, this central column should be edited in a way that it integrates the code of both side columns. Once the conflict is solved and the new source code (the central column) is saved, the Meld tool can be closed. Then the or  operation can continue.

For more information on merging and solving conflicts see:
 * How merge conflicts are presented with.
 * Basic merge conflicts and Git Tools - Advanced Merging.
 * Resolving a merge conflict using the command line.
 * External merge and diff tools to use when you encounter a Git conflict.

Inspect changes
Inspect the history of a single file through various commits with the operation:

Where can be any directory or file. Instead of, also the shorthands or  can be used.

Inspect changes between two branches
Inspect the changes between two branches with the and  operations with the names of the branches:

The operation shows the commits, while  shows the actual changes in the files.

Reset files and directories
If you accidentally made modifications to a file or directory, you may want to completely revert these changes, to get the previous state of the source code.

This can be done quickly using the operation:

This will restore the (a file or a directory) to the state it is at the tip of the branch, discarding changes that haven't been committed. If is the single dot, it will restore all files in the current directory.

If you have accidentally added files and directories you can use the operation:

This will forcefully delete all files and directories that are not being tracked by the repository, that is, those that have not been included previously with the  operation.

To completely reset the repository, losing all uncommitted modifications, use the operation:

Where is the the tip of the  repository. Another commit can also be used.

The operation also reverts changes. However, this command does this by adding another commit to the history; in many cases this is not desired.

Pruning old branches
If you have committed many branches to the repository, you may wish to remove these branches from your local system as they have already been merged. The branch in the repository online can be deleted immediately after merging. Then you can remove the local references to that branch, using the or  options to the  and  operations.

Finally you can delete the branches locally

It is also a good practice to do garbage collection after a while, by using the operation. This will cleanup unnecessary files, and compress local file revisions, in order to optimize local disk usage of the repository.

Working with patches
Although Git allows you to merge different branches of code with (in your computer) or a pull request (remote repository), there are times when it may be desirable to create a traditional "patch", which can be sent as an attachment through email. The following workflow explains how to do this.

Creating patches

 * You should be developing your new code in a secondary branch of your repository, and not in the master branch. So the first step is to make sure you are in the correct branch.


 * Now use against the master branch, and use the  option to redirect the result to standard output; then redirect the standard output to a file, which for convenience is created above the source code directory.


 * Another method is

The number of circumflex carets or the number  indicate the number of commits that should be considered, that is,  or  will create three patches for three commits.

This will create a patch or series of patches with the following naming convention

where is a number from  to, and the commit message forms the majority of the file name, for example,

Applying patches
Git can merge patches or diffs. To know more about this process read Applying patches with Git.

If you already have the patch file in your system, just apply it.

You can use to download a patch from a website, and then apply it through.

Add or  at the end of the URL of a GitHub commit, pull request, or compare view so that the website shows you the plain text view of that page.
 * Regular commit page: https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621
 * Diff page: https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621.diff
 * Patch page: https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621.patch

You can point to a particular commit patch in the repository, and pipe it directly to  to apply the patch.

curl https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621.patch | git apply -

Reversing a patch
When you apply a patch you modify some files. However, these modifications aren't permanent until you commit the changes. Therefore, if you want to revert a patch use the following instructions.

This will revert the changes applied, if you still have access to the original patch file.

Alternatively, this will remove non-committed changes to the branch.

Stashing git commits
Say that you're working on a branch and you find yourself making some modifications to the source that are out of the scope of your current branch; in other words, those changes would be better in another branch instead of the current one. The command can be used to temporarily store those uncommitted local changes.

If in the future you want to use those commits, you can "pop" the commits out of the stash, and into your working branch.

Or if you decide that you don't like those saved commits anymore, you may drop the commits from the stash entirely.

You can list multiple stash commits with

To learn more, read Useful tricks you might not know about Git stash.

Check out GitHub requests locally
Checkout GitHub pull requests locally

FreeCAD revision number
In contrast to subversion, which uses a consecutive number for its revisions, Git produces SHA-1 hash values with every commit. A hash value is a long alphanumeric string that looks like this

Latest revision number
To find the latest revision number of a particular branch use the operation with the  option. Give the name of the branch, remote repository, tag, or a special pointer like, to indicate the last commit in that particular object.

Or browse the repository on GitHub, and read the amount of commits reported in the particular branch.

Revision number of a specific commit hash
Since the hash is an alphanumeric string it is not very useful to decide if a certain commit is older or newer than another hash. To find the revision number of a particular hash, again use the operation; the input can be the full hash, or a partial hash that is unique, usually the first 7 digits are enough.

Revision hash of a specific commit number
If we have the commit number, say, 15000, and we want to find the corresponding hash, we need to calculate the number of commits since this point until the last commit. First, get the latest commit number.

Then subtract the commit that we want.

Then use the operation to show all commits and hashes. The option jumps the difference in commits that we calculated so that we go directly to the hash that we are looking for.

Since the log may show you two close commits, confirm it's the right commit number. If it's off by one, just pick the next commit in the sequence (before or after) and check again.


 * Show the commits immediately before a particular commit in GitHub: in the address bar of the browser, change the word to  to show a list.
 * Finding the revision number of the commit
 * Finding the revision number of the commit
 * Finding the corresponding hash value to a particular commit number

Revision number in FreeCAD's interface
The version number that appears with the Std About tool is defined in, which is created at compile time when the tool is run. Read Extract version number from git source for more information.

Adding other repositories (remotes)
Several collaborators of the FreeCAD project have their own Git repositories where they build up their work or where they experiment new ideas before they are ready to be included in the official source code. You may want to get their sources in order to test their code yourself when they make a pull request.

Use the command to add these other repositories so that you can  and  their code.

For example, lets add Bernd's remote repository:

The command downloads the references from that remote repository.

List all branches in your own repository, and those from your added remotes. Bernd's branches will display as.

Now, lets view a summarized list of the last 10 commits of bernd's branch.

Now we can checkout the desired branch to inspect.

Then we can create a local branch that is based on the remote branch. This local branch we can modify, and add our own code to it.

You may wish to the newly obtained branch onto the  branch to make sure it is using the latest code. If there are conflicts, they will have to be solved at this point.

The new branch is ready to be modified and compiled as described in Compiling.

Head to the development section of the FreeCAD forum to discuss more about development.