Source code management/pl

Wprowadzenie
Głównym narzędziem do zarządzania kodem źródłowym projektu FreeCAD jest Git, który może być łatwo zainstalowany w większości systemów operacyjnych z menedżera pakietów lub bezpośrednio z strony internetowej Git. Zaleca się zapoznanie się ze środowiskiem Git przed bezpośrednią pracą z kodem źródłowym FreeCAD. Odwiedź stronę dokumentacja Git, aby zapoznać się z podręcznikiem źródłowym, a także Pro Git book, aby nauczyć się korzystać z systemu w sposób ogólny. Niniejszy dokument koncentruje się na wykorzystaniu Git do rozwoju FreeCAD. Kompilacja programu FreeCAD jest opisana na stronie Kompilacja.

Chociaż Git jest przede wszystkim aplikacją terminalową, istnieje wiele klientów graficznych, które ułatwiają pracę z gałęziami, nanoszenie poprawek i wysyłanie żądań ściągnięcia do gałęzi głównej. Przykłady obejmują gitk (pierwszy opracowany interfejs graficzny), gitg (Gnome), qgit (Qt), tig (Ncurses), git-cola i GitKraken (własnościowy). Krótkie wprowadzenie do tego narzędzia można znaleźć w Rozwój FreeCAD z GitKraken.

Uwaga: jeśli to wszystko zaczyna przyprawiać cię o zawrót głowy, istnieje bardzo dobra nietechniczna seria o tym, jak używać Gita i Githuba, zatytułowana "Git i Github dla poetów".

Dostęp do kodu źródłowego
Każdy może uzyskać dostęp i kopię kodu źródłowego FreeCAD, ale tylko menedżerowie projektu FreeCAD mają do niego dostęp do zapisu. Możesz uzyskać kopię kodu, studiować go i modyfikować, ale jeśli chcesz, aby Twoje zmiany zostały włączone do oficjalnego kodu źródłowego, musisz wykonać "pull request" w stosunku do głównego repozytorium, aby Twoje modyfikacje mogły zostać sprawdzone przez menedżerów. Ten styl rozwoju jest znany jako Dyktator i porucznicy, ponieważ główni programiści (dyktatorzy) i zaufani programiści (porucznicy) filtrują kod nadsyłany przez niezależnych programistów i użytkowników.

Jeśli zmiany w kodzie źródłowym są znaczące, zaleca się wyjaśnienie ich w sekcji pull request na forum FreeCAD.



Oficjalne repozytorium GitHub
Kod źródłowy programu FreeCAD jest dostępny w serwisie Github, https://github.com/FreeCAD/FreeCAD

Aby móc wnieść swój kod, należy posiadać konto GitHub account.

W przeszłości kod źródłowy był przechowywany w repozytorium SVN, https://free-cad.svn.sourceforge.net/svnroot/free-cad. Przeniesiono je na GitHub, 10 października 2011 r. za pomocą commit 120ca87015.


 * W związku z tym istnieje wiele zmian, które zostały wprowadzone przed tym czasem, a które nie są zapisane we współczesnej historii commitów Git. Więcej na ten temat można przeczytać na stronie Historia.

Ustawianie nazwy użytkownika Git
Programiści powinni wysyłać kod do swojego osobistego repozytorium używając swojej nazwy użytkownika GitHub. Jeśli nie jest ona jeszcze ustawiona globalnie, można ją ustawić lokalnie dla bieżącego repozytorium Git w następujący sposób:

Gdzie reprezentuje twoje pełne imię i nazwisko lub pseudonim, używane do identyfikacji autora danego commitu, a  oznacza nazwę twojego konta na GitHubie.

Repozytoria zdalne
Proszę przeczytać Jaka jest różnica między origin a upstream na GitHubie? (Stackoverflow), aby pomóc w zrozumieniu różnicy między a  w kontekście Git. Ta sekcja wyjaśnia, jak ustawić właściwe repozytoria dla rozwoju. Zasadniczo:
 * to Twój osobisty fork oficjalnego repozytorium FreeCAD, czyli https://github.com/GITHUB_USERNAME/FreeCAD
 * to oficjalne repozytorium FreeCAD, czyli https://github.com/FreeCAD/FreeCAD.

To rozróżnienie jest ważne, ponieważ najpierw należy napisać kod we własnej kopii repozytorium, a dopiero potem przesłać zmiany do oficjalnego repozytorium.

W oparciu o powyższe informacje można skonfigurować środowisko programistyczne Git na dwa sposoby:
 * Pierwsza metoda: rozwidlenie na GitHubie i sklonowanie go lokalnie.
 * Druga metoda: sklonuj FreeCAD bezpośrednio na lokalnym komputerze i dostosuj zdalne serwery.

Zalecamy pierwszą metodę, ponieważ jest ona o jeden krok krótsza.

Metoda pierwsza: Rozwidlenie na GitHub i sklonowanie swojego widelca lokalnie
Najpierw rozwidlisz repozytorium FreeCAD na GitHubie, następnie sklonujesz to osobiste rozwidlenie na swój komputer, a na koniec ustawisz repozytorium.
 * Zaloguj się na swoje konto GitHub.
 * Przejdź do oficjalnego repozytorium FreeCAD: https://github.com/FreeCAD/FreeCAD
 * W prawym górnym rogu strony naciśnij przycisk "Fork". Spowoduje to utworzenie osobistej kopii repozytorium FreeCAD pod Twoją nazwą użytkownika GitHub:
 * Na swoim komputerze sklonuj nowo utworzony fork programu FreeCAD. Zostanie on utworzony wewnątrz katalogu.


 * Po zakończeniu pobierania wprowadź nowy katalog źródłowy i ustaw repozytorium.


 * Potwierdź swoje zdalne repozytoria za pomocą ; rezultat powinien być podobny do tego


 * Teraz można rozpocząć prace rozwojowe.

Metoda druga: Sklonuj FreeCAD bezpośrednio na swój komputer lokalny
Najpierw rozwidlisz repozytorium FreeCAD w serwisie GitHub, jednak oryginalne repozytorium FreeCAD sklonujesz na swój komputer lokalny, a następnie zmienisz swoje zdalne adresy za pomocą terminala.
 * Zaloguj się na swoje konto GitHub.
 * Przejdź do oficjalnego repozytorium FreeCAD: https://github.com/FreeCAD/FreeCAD
 * W prawym górnym rogu strony naciśnij przycisk "Fork". Spowoduje to utworzenie osobistej kopii repozytorium FreeCAD pod Twoją nazwą użytkownika GitHub:
 * Sklonuj oryginalne repozytorium FreeCAD. Zostanie ono utworzone wewnątrz katalogu.


 * Po zakończeniu pobierania należy wejść do nowego katalogu źródłowego i ustawić repozytorium.


 * Następnie należy skonfigurować repozytorium.


 * Potwierdź swoje zdalne repozytoria za pomocą ; rezultat powinien być podobny do tego


 * Teraz można rozpocząć prace rozwojowe.

Jeśli z jakiegoś powodu zdalne repozytoria istnieją, ale wskazują na niewłaściwy adres, możesz naprawić sytuację, zmieniając nazwę zdalnego repozytorium. Na przykład powinno wskazywać na Twój osobisty fork. Jeśli wskazuje na oryginalne repozytorium FreeCAD, zmień nazwę tego zdalnego na i ręcznie dodaj repozytorium.

Można również wyświetlić więcej informacji za pomocą słowa kluczowego.

Odgałęzienia
Zamiast pracować na głównej wersji kodu, najlepsze praktyki Git zalecają tworzenie nowej gałęzi za każdym razem, gdy chcesz pracować nad nową funkcjonalnością. Gałęzie są niedrogie, nie kopiują całego drzewa źródłowego, a jedynie tworzą punkt w czasie, na którym będziesz pisał kod. W ten sposób gałęzie pomagają oddzielić prace w toku od głównego kodu.

Korzystanie z nowej gałęzi odbywa się w dwóch etapach: najpierw należy utworzyć gałąź, a następnie przejść do niej:

Alternatywnie można wykonać obie czynności za pomocą jednej instrukcji:

Teraz możesz zmieniać gałęzie za pomocą, kiedy tylko chcesz nad nimi pracować. Aby zobaczyć gałęzie w projekcie i bieżącą gałąź, użyj samej operacji lub dodaj  lub, aby uzyskać więcej informacji:

Po wprowadzeniu zmian i ich zatwierdzeniu użyj operacji z następującymi opcjami, aby wyświetlić gałęzie

Committing
Gdy już znajdziesz się w nowej gałęzi, edytuj wybrane pliki źródłowe za pomocą edytora tekstu. Aby sprawdzić, które pliki zostały zmodyfikowane, użyj operacji i. Kiedy będziesz zadowolony z wprowadzonych zmian, zapisz je za pomocą operacji :

W przeciwieństwie do SVN, musisz wskazać, które pliki mają być commitowane. Użyj opcji, aby zapisać zmiany we wszystkich plikach, które zostały zmienione. Otworzy się edytor tekstu, na przykład lub, aby umożliwić napisanie wiadomości do zgłoszenia commit.

Ewentualnie dodaj wiadomość w samym zgłoszeniu commit:

Jeśli tworzysz nowe pliki lub katalogi, musisz najpierw użyć operacji, aby dodać je do lokalnego repozytorium przed zatwierdzeniem zmian.

Gdzie może być dowolnym katalogiem lub plikiem.

Pisanie dobrych komunikatów zgłoszeń commit
Powinieneś starać się pracować małymi krokami, czyli często zatwierdzać zmiany po wprowadzeniu niewielkiego dodatku do swojego kodu. Jeśli nie potrafisz streścić swoich zmian w jednym zdaniu, to prawdopodobnie minęło zbyt dużo czasu od wykonania zgłoszenia commit.

W przypadku dużych zmian ważne jest, abyś miał pomocne i przydatne opisy swojej pracy. FreeCAD przyjął format wspomniany w książce Pro Git, który składa się z krótkiej wiadomości, a następnie większego akapitu opisowego.

Jeśli wykonujesz wiele powiązanych prac w gałęzi, powinieneś wykonać wiele małych commitów (zobacz post na forum ). Gdy chcesz scalić te zmiany w gałęzi głównej, powinieneś wydać polecenie:

aby zobaczyć poszczególne komunikaty zgłoszeń commit. Dzięki temu można napisać wysokiej jakości komunikat podczas wykonywania scalania.

Kiedy łączysz się z wersją master, użyj opcji i wykonaj commit z wysokiej jakości komunikatem commit. To pozwoli ci być bardzo liberalnym w swoich zgłoszeniach commit i pomoże zapewnić dobry poziom szczegółowości w komunikatach commit bez tak wielu odrębnych opisów.

Squashing commits
Squashing odnosi się do procesu łączenia różnych kolejnych commitów w jeden. Może to być pożądane, jeśli wykonałeś wiele małych commitów, które chcesz przedstawić jako jeden commit, na przykład przy zmianie pojedynczej zmiennej, poprawianiu błędów ortograficznych i poprawianiu odstępów w kodzie. Powinieneś zgnieść tylko małe commit'y do pojedynczego pliku. Duże zmiany w kodzie w wielu plikach powinny zawierać pełną historię commit'ów.

Dzięki możesz zobaczyć wiele commitów po kolei, z najnowszym na górze. W tym przykładzie, zaczynając od "cechy A", powstało wiele commitów implementujących "cechę B"; chcielibyśmy zebrać wszystkie commity należące do "cechy B" w jeden.

Użyj operacji z opcją  lub, aby wybrać różne commity i je usunąć. Użyj hash commitu znajdującego się tuż przed pierwszym, który chcesz usunąć, w tym przypadku tego odpowiadającego "cechom A".

(WSKAZÓWKA: Jeśli wiesz, ile commitów chcesz edytować, możesz użyć, aby pracować na ostatnich commitach).

Edytor wiersza poleceń, taki jak lub, otworzy się, aby ponownie wyświetlić listę commitów, teraz ze starszym commitem na górze. Przed każdym commitem pojawi się słowo. Usuń słowo i wpisz w jego miejsce słowo  lub po prostu literę, z wyjątkiem pierwszego wpisu; ten commit jest najstarszy, więc wszystkie następne zostaną w nim zebrane.

Zapisz plik i zamknij edytor.

Edytor zostanie ponownie otwarty. Teraz możesz dodać dłuższy komunikat opisujący wszystkie zmiany, tak jakby były pojedynczym commitem. Zapisz plik i ponownie zamknij edytor. W ten sposób zakończysz łączenie tych commitów w jeden, z nowym komunikatem commit, który napisałeś.

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

When coding for FreeCAD, we ask that you begin each commit message with the module that it affects. For example, a commit message for a change to sketcher might be: Sketcher: make straight lines curve a bit

Straight lines are sort of ugly, so this commit adds a little bit of curvature to them, so they are more visually pleasing. They also sparkle some, and change colors over time.

Fixes bug #1234.

Your PR will be easier to review, and faster to be merged, if you are careful to use rebase to structure and describe your commits before submitting.

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.

To recap, the development process looks like this:
 * 1) Fork FreeCAD and get a local copy of that fork.
 * 2) Create a branch on your fork and change to that branch.
 * 3) Code! Commit and much or as little as you like, writing good commit messages to keep track of what you are doing.
 * 4) When you are satisfied with your work, use  (where n is the total number of commits you've made) to collapse your commits into a logical set with good commit messages (each message should begin with the name of the module it affects, e.g. "Sketcher: make straight lines curve a bit").
 * 5) Use GitHub to submit your code as a "Pull Request (PR)" as described below.

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.

GitHub will show you a text editor so you can write a message documenting your changes: this editor will be pre-filled with a welcome message (that you can delete), a checklist (that you should go through), and a reminder to document your change on the wiki when it's accepted. To use the checklist, go through each item in turn and change the to  to indicate that you've done that step. GitHub 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. Double-check these for things like stray blank lines you didn't mean to add, or huge formatting changes that your IDE decided to make behind your back.

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

Blaming
Add content from https://forum.freecadweb.org/viewtopic.php?f=23&t=55943&p=481483#p481287

Bisect
is a method to find the specific commit that introduced a bug.

You need to find 2 commits:
 * A good commit (for example ) before the system broke.
 * A bad commit (for example ) after the system broke.

Then enter this from the terminal:

Result: will check out the mid point between the two commits.

The next step is to build and test the code. If the system works, continue the process by typing:

Repeat the previous step of building the code and testing it.

If the system is broken, type:

Repeat the previous steps applying or  depending on the outcome of your tests.

Eventually, will tell you that  is the first bad commit.

Finally, to exit the bisect process, type:

Note: takes a long time if good and bad are far apart.

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.