Source code management/it

Il nostro principale strumento di gestione del codice sorgente distribuito è Git. Questo articolo spiega come usarlo e quali sono le regole generali applicabili per FreeCAD. Prima di lavorare con il codice sorgente di FreeCAD, si consiglia vivamente di imparare come funziona Git (per Git ci sono un sacco di tutorial e di documentazione disponibile su Internet)

Ci sono anche molti buoni clienti grafici per git, come git-cola, che facilitano l'intero processo di gestione del repositorio git

Accesso al codice sorgente
Tutti possono accedere e ottenere una copia del codice sorgente di FreeCAD, ma solo i gestori del progetto di FreeCAD hanno l'accesso in scrittura. È possibile ottenere una copia del codice, studiarlo e modificarlo come si vuole, ma se si apporta una modifica che si desidera vedere inclusa nel codice sorgente ufficiale, è necessario fare una richiesta di pull nella sezione pull requests del forum di FreeCAD.

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.



Repositorio ufficiale GitHub
Un modo semplice per iniziare a lavorare con il codice sorgente di FreeCAD è quello di utilizzare il repositorio ufficiale su

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

Impostare il proprio nome utente in Git
Gli utenti devono connettersi al proprio repository del progetto utilizzando il proprio nome utente di GitHub. Se il nome utente non è già impostato a livello globale, è possibile impostarlo a livello locale per il repository Git attuale in questo modo:

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,
 * 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.

Clonare con git sulla propria macchina locale
È anche possibile iniziare, senza utilizzare il pulsante "fork":
 * 1) Clonare il codice di FreeCAD con git:
 * git clone https://github.com/FreeCAD/FreeCAD.git
 * 1) Fare le proprie modifiche al codice
 * 2) Creare un nuovo ramo
 * 3) Eseguire il Checkout a tale nuovo ramo
 * 4) Eseguire il Commit delle modifiche a tale nuovo ramo
 * 5) Creare un prorpio account a un server git pubblico (GitHub, GitLab, etc...)
 * 6) Trasferire il proprio ramo su tale server

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.

Processo di sviluppo Git
Prima di tutto non sviluppare mai sul ramo master! Creare sempre un ramo locale di sviluppo. Per imparare come farlo, consultare Git-Branching-Basic-Branching-and-Merging chapter on git-scm.



Ramificazioni
Una caratteristica importante di Git è che è estremamente facile lavorare con i rami e poi fonderli. Le procedure ottimali raccomandano di creare un nuovo ramo ogni volta che si desidera lavorare su una nuova funzionalità. Per creare un ramo fare in questo modo:

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:

oppure, eseguire entrambe le operazioni in una sola:

è sempre possibile verificare in quale ramo si stà operando con:

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

Invio
Dopo aver prodotto un po' di lavoro, si può inviarlo con:

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:

A differenza di SVN, è necessario indicare specificare quali file sono da inviare (o tutti con l'opzione -a). Il proprio editor di testo si apre per consentire di scrivere un messaggio di commit.

Alternatively add the message in the commit itself

Scrivere buoni messaggi di commit
Si dovrebbe cercare di lavorare in piccole parti. Se non è possibile riassumere le proprie modifiche in una sola frase, è probabile che sia passato troppo tempo da quando si è fatto l'ultimo commit. Inoltre è importante che le descrizioni del lavoro siano dettagliate e utili. Per i messaggi di commit, FreeCAD adotta un formato menzionato nel libro Pro Git.

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.

Breve riepilogo delle modifiche (circa 50 caratteri) Se è necessario, testo esplicativo più dettagliato. Utilizzare circa 72 caratteri. In alcuni contesti, la prima riga è trattata come oggetto di un messaggio e il resto del testo come il corpo. E'fondamentale lasciare una riga vuota per separare il riassunto dal corpo (a meno che non si ometta per intero il corpo); se le due parti sono unite gli strumenti come rebase possono confondersi. Ulteriori paragrafi vanno dopo una riga vuota. - Anche gli elenchi puntati sono validi - Tipicamente per le voci dell'elenco si usa un trattino o un asterisco preceduto da uno spazio bianco, e sono intervallate da una riga vuota, ma queste convenzioni possono variare

Se si sta facendo diversi lavori connessi, qui viene suggerito che si dovrebbero fare altrettanti invii, grandi o piccoli, secondo come è necessario e descriverli con brevi messaggi di commit. Quando si desidera unirli, fare un log master git..BRANCH e utilizzare il risultato come base per il messaggio di commit. Poi, quando si uniscono al master usare l'opzione --squash e inviarlo con il messaggio di commit. Questo permette di essere molto liberi con il commit e contribuisce a fornire un buon livello di dettagli nei messaggi di commit senza tante descrizioni distinte.

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

Pubblicare il proprio lavoro nel proprio repositorio GitHub
Dopo aver fatto un pò di lavoro nel ramo locale e averlo inviato (questo inviato significa a livello locale) si può inviare il proprio repository sul server. Questa azione apre il ramo al pubblico e permette agli sviluppatori principali di rivederlo e di integrarlo nel ramo master.

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.

The regular developer doesn't have write access to the repository https://github.com/FreeCAD/FreeCAD, therefore, you shouldn't 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  action. 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.

Resolving merge conflicts
Merging local branches with will occasionally present conflicts, as the files may have been changed at the same time in the same place. If this happens you should fix the files, and re-merge.


 * 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 the changes of a single file through various commits:

Creating patches from Git
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.


 * 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 via git
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 in git
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 starting from 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 in is defined in, which is created at compile time when the  tool is run. Read Extract version number from git source for more information.

See the compile on Unix page for the full information on compiling FreeCAD.

Repositori alternativi
La bellezza di git è che tutti possono clonare un progetto, e iniziare a modificare il suo codice. Diversi collaboratori frequenti del progetto di FreeCAD hanno un proprio repository git, dove costruiscono il loro lavoro prima che sia pronto per essere incluso nel codice sorgente ufficiale, o dove sperimentano semplicemente delle nuove idee. In alcuni casi, si potrebbe desiderare di clonare il codice FreeCAD da uno di loro, invece del repository ufficiale, per beneficiare dei cambiamenti fatti da questi utenti.

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. In certain cases you might want to clone your FreeCAD sources from these other repositories to test their code.

È anche possibile collegare diversi repository remoti a un medesimo codice git locale utilizzando il comando "git remote". Questo è utile per mantenere la sincronia con il ramo principale del codice, ma tenere d'occhio il lavoro degli altri sviluppatori.

Head to the development section of the FreeCAD forum to discuss more about development of new features. See also Compiling for instructions on compiling FreeCAD.

Ulteriori letture

 * Git for the lazy
 * Git pro libro on-line