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

Możesz użyć ponownie, aby zaobserwować historię nowych zgłoszeń commit. W tym przypadku pojawi się tylko pojedynczy commit dla "cechy B", na wierzchu niezmodyfikowanego commitu dla "cechy A".

Podczas kodowania dla FreeCAD prosimy, abyś rozpoczynał każdą wiadomość commit od modułu, którego dotyczy. Na przykład wiadomość commit dla zmiany w Szkicowniku może wyglądać następująco: 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.

Twój PR będzie ułatwiał przeglądanie i szybciej zostanie scalony, jeśli będziesz uważał, aby używać rebase do strukturyzacji i opisywania swoich zgłoszeń commit przed wysłaniem.

Przesłanie pracy do repozytorium GitHub
Gałęzie lokalne na Twoim komputerze nie są automatycznie synchronizowane ze zdalnymi serwerami, które określiłeś jako lub  ( patrz Remote repositories). Musisz jawnie wysłać gałęzie na zdalne serwery, do których wymagany jest dostęp z prawem zapisu. Gdy to zrobisz, gałęzie staną się publiczne i dostępne do wglądu dla innych programistów.

W przypadku programu FreeCAD powinieneś przesłać swoją lokalną gałąź do zdalnego repozytorium, czyli do. Musisz podać swoją nazwę użytkownika i hasło za każdym razem, gdy wykonujesz push, chyba że ustawiłeś Buforowanie poświadczeń. Przeczytaj Pushing commit do zdalnego repozytorium, aby uzyskać więcej informacji.

Podczas pracy z pojedynczą gałęzią może zajść potrzeba wielokrotnego, interaktywnego przekształcania, usuwania i poprawiania zgłoszeń commit. W takim przypadku historia oddziału (branch) nie będzie prosta i nie będzie można jej przesłać do zdalnego repozytorium. Może pojawić się komunikat taki jak poniżej, mówiący, że nie jest możliwe wykonanie pchnięcia "fast-forward".

Aby ostatecznie przepchnąć swoją gałąź do zdalnego repozytorium, musisz wykonać "force push". Spowoduje to całkowite nadpisanie zdalnej gałęzi aktualną gałęzią, którą mamy w trybie offline.

Zwykły programista nie ma dostępu do zapisu w repozytorium https://github.com/FreeCAD/FreeCAD, dlatego nigdy nie należy umieszczać kodu na tym zdalnym serwerze.

Rebasing from upstream
Podczas gdy Ty pracujesz nad swoją własną gałęzią, oficjalny kod programu FreeCAD "idzie do przodu" dzięki zgłoszeniom commit innych deweloperów i w ten sposób zaczyna odbiegać od kodu, który masz w swoim osobistym forku.

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

Dlatego, gdy jesteś gotowy do połączenia swojego oddziału z głównym repozytorium FreeCAD, musisz "przebudować" swoją kopię repozytorium, tak aby była jak najbardziej zbliżona do oficjalnego repozytorium. Zapoznaj się z treścią Git Branching - Rebasing, aby uzyskać więcej informacji.

Spowoduje to pobranie kodu z gałęzi repozytorium  (oficjalne źródło programu FreeCAD) i scalenie go z Twoją bieżącą gałęzią, tak aby Twoje zmiany znalazły się na wierzchu najnowszego oficjalnego kodu. Jeśli nikt nie zmodyfikował tych samych plików, co Ty, to scalenie przebiegnie bez problemów. Jeśli niektóre pliki zostały zmienione w tym samym czasie przez różne osoby, może istnieć konflikt, który należy rozwiązać.

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

Podsumowując, trzeba być w odpowiedniej gałęzi, przebudować kod do wykonania upstreamu, a następnie wykonać push.

Operacja jest równoważna operacji, po której następuje. Gdy użyta jest opcja, zamiast prostego wykonywana jest operacja.

Scalanie gałęzi (pull request)
Po lokalnym wprowadzeniu zmian, przebudowaniu swojej gałęzi z repozytorium upstream i umieszczeniu swojej gałęzi online, możesz zainicjować "pull request". Prośba pull request mówi administratorom oficjalnego repozytorium FreeCADa, że chcesz połączyć nowy kod w swojej gałęzi z oficjalnym kodem.

Podsumowując, proces rozwoju wygląda następująco:
 * 1) Utwórz fork programu FreeCAD i uzyskaj lokalną kopię tego forka.
 * 2) Utwórz gałąź na swoim rozwidleniu i zmień na tę gałąź.
 * 3) Koduj! Udostępniaj tyle lub tak mało, jak chcesz, pisząc dobre komunikaty commit, aby śledzić, co robisz.
 * 4) Gdy będziesz zadowolony ze swojej pracy, użyj  (gdzie n jest całkowitą liczbą zgłoszeń commit, które wykonałeś), aby zebrać swoje commity w logiczny zestaw z dobrymi komunikatami do zgłoszeń commit (każdy komunikat powinien zaczynać się od nazwy modułu, którego dotyczy, np. "Sketcher: make straight lines curve bit").
 * 5) Użyj GitHuba, aby przesłać swój kod jako "Pull Request (PR)", jak opisano poniżej.

Gdy tylko umieścisz kod w swoim repozytorium, GitHub da Ci możliwość porównania i utworzenia pull requestu do repozytorium. Po naciśnięciu przycisku otworzysz interfejs, który pozwoli Ci wybrać, które repozytorium jest "bazą", czyli celem scalania, a które "głową", czyli Twoim dodatkowym kodem. System szybko sprawdzi, czy nie ma konfliktów z plikami, które zmodyfikowałeś. Jeśli pracowałeś nad plikami, których nikt nie dotykał, twoja gałąź będzie mogła zostać scalona bez problemów.

GitHub wyświetli edytor tekstu, w którym można napisać wiadomość dokumentującą zmiany: edytor ten będzie wstępnie wypełniony wiadomością powitalną (którą można usunąć), listą kontrolną (którą należy przejrzeć) oraz przypomnieniem o konieczności udokumentowania zmiany na wiki, gdy zostanie zaakceptowana. Aby skorzystać z listy kontrolnej, przejdź przez każdy element po kolei i zmień na, aby zaznaczyć, że wykonałeś dany krok. GitHub wyświetli także liczbę commitów w Twojej gałęzi, liczbę plików, które zostały zmodyfikowane, oraz widok pokazujący różnice między "bazą" a "głową", aby każdy mógł natychmiast zobaczyć, jakie są Twoje zamierzone modyfikacje. Sprawdź dwukrotnie, czy nie ma tam takich rzeczy, jak zabłąkane puste linie, których nie chciałeś dodać, lub ogromne zmiany formatowania, które IDE postanowiło wprowadzić za Twoimi plecami.

Kliknij, aby kontynuować. Pojawi się komunikat informujący, że kod musi zostać sprawdzony. Jest to system, który automatycznie kompiluje program FreeCAD i uruchamia testy jednostkowe. Jeśli testy przejdą pomyślnie, pull request będzie miał większe szanse na połączenie z głównym kodem, w przeciwnym razie zostanie sporządzony raport wskazujący napotkane błędy. Zobacz FreeCAD pull requests.

Some checks haven’t completed yet


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

Jeśli testy zakończą się powodzeniem, pojawi się komunikat taki jak poniżej:

All checks have passed


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

Ta gałąź nie ma konfliktów z gałęzią podstawową Tylko osoby z prawem zapisu do tego repozytorium mogą łączyć zgłoszenia pull request.

Teraz musisz poczekać, aż administratorzy połączą Twoją gałąź. Zostaniesz o tym poinformowany.

Jeśli chcesz, możesz usunąć gałąź, która została właśnie scalona, a nawet cały swój fork programu FreeCAD, ponieważ Twój własny kod jest już dołączony na końcu gałęzi głównej.

możesz kontynuować pracę na tej samej gałęzi, czekając na zatwierdzenie scalenia. Jeśli ponownie wykonasz, drugi commit scalenia zostanie umieszczony w kolejce w tym samym żądaniu ściągnięcia, a kolejny automatyczny test zostanie wykonany. Oznacza to, że podczas gdy twoje scalenia nie są jeszcze zatwierdzone przez administratorów, możesz nadal wysyłać zmiany do swojego repozytorium, a to spowoduje umieszczenie tych zgłoszeń commit w kolejce tego samego żądania wyciągnięcia do repozytorium. Używanie pojedynczego żądania pull do kolejkowania wielu pojedynczych zgłoszeń commit jest często pożądane w przypadku małych zmian. W przypadku dużych zmian w kodzie źródłowym, należy utworzyć inną gałąź, rozwijać w niej swoje funkcje, a następnie wysłać osobne żądanie pull request dla tej gałęzi.

Przetłumaczono z www.DeepL.com/Translator (wersja darmowa)

Interfejs pull request może być używany za każdym razem, gdy chcesz przesłać kod z własnego repozytorium do innego repozytorium w GitHubie. Można go również używać do scalania kodu w odwrotnym kierunku, z gałęzi innych osób do własnej, a nawet pomiędzy własnymi gałęziami. W tym ostatnim przypadku, ponieważ jesteś właścicielem gałęzi, możesz od razu zatwierdzić scalanie.

Utrzymywanie aktualnego repozytorium GitHub
Po rozwidleniu FreeCAD, Twoje osobiste repozytorium istnieje niezależnie od oryginalnego. Kiedy oryginalne repozytorium będzie miało nowe zgłoszenia commit, GitHub poinformuje Cię, że Twoje osobiste repozytorium jest opóźnione pod względem liczby zgłoszeń commit:

W podobny sposób, jeśli utworzyłeś gałąź rozwojową z nowym kodem, GitHub poinformuje Cię, że ta gałąź wyprzedza Cię w liczbie zgłoszeń commit. To znaczy, że ta gałąź zawiera zmiany, które nie zostały jeszcze scalone z oficjalnym repozytorium FreeCAD:

Podczas rozwijania możliwe są oba przypadki, ponieważ Twoja własna gałąź może nie zawierać zgłoszeń commit innych deweloperów, ale zawierać nowe, napisane przez Ciebie:

Podczas tworzenia kodu zaleca się, abyś zmienił bazę gałęzi, w której aktualnie pracujesz, ponieważ dzięki temu Twoja gałąź będzie zawsze wyprzedzać kod główny FreeCAD.

Jeśli chodzi o twoją oryginalną gałąź, to nigdy nie będzie ona automatycznie aktualizowana przez GitHub. Musisz o to zadbać samodzielnie. Przełącz się na gałąź, a następnie z  (co spowoduje pobranie  i ), a następnie przepchnij zaktualizowaną gałąź  do swojego zdalnego repozytorium.

Po wykonaniu tych czynności GitHub poinformuje Cię, że jesteś zsynchronizowany z repozytorium.

Teraz, gdy twój jest aktualny, możesz zdecydować się na przejście do niego i usunąć inną gałąź, której używałeś wcześniej do rozwijania funkcji.

Aby usunąć gałąź w zdalnym repozytorium, można użyć operacji. Zwykle pcha się lokalną gałąź. Spowoduje to utworzenie zdalnej gałęzi o tej samej nazwie co lokalna.

Jeśli jednak użyjesz zapisu, lokalna gałąź zostanie utworzona w zdalnym repozytorium pod inną nazwą:

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.