Gestion du code source
Le principal outil de gestion de code source du projet FreeCAD est Git, qui peut être facilement installé dans la plupart des systèmes d'exploitation à partir d'un gestionnaire de paquets ou directement à partir de Git's website. Nous vous conseillons de vous familiariser avec Git avant de travailler directement avec le code source FreeCAD. Visitez la page Git documentation pour obtenir le manuel de référence, ainsi que le Pro Git book pour apprendre à utiliser le système de manière générale. Le présent document porte sur l'utilisation de Git pour le développement FreeCAD. La compilation de FreeCAD est décrite dans Compilation.
Bien que Git soit principalement une application de terminal, il existe de nombreux clients graphiques qui facilitent le travail avec les branches, l’application de correctifs et la soumission de demandes d'extraction à une branche principale. Les exemples incluent gitk (la première interface graphique développée), gitg (Gnome), qgit (Qt), tig (Ncurses), git-cola et GitKraken (propriétaire). Veuillez consulter Developing FreeCAD with GitKraken pour une introduction sommaire à cet outil.
Accès au code source
Tout le monde peut accéder et obtenir une copie du code source de FreeCAD, mais seuls les gestionnaires de projet(s) peuvent en modifier le contenu. Vous pouvez avoir une copie du code, l'étudier et le modifier comme vous le souhaitez, mais si vous voulez que vos modifications soient prises en compte dans le code source officiel, vous devez effectuer un "pull request" sur le dépôt master. Les gestionnaires pourront alors vérifier vos modifications avant de les valider. Cette façon de développer est connue sous le nom de flux de travail des dictateurs et des lieutenants où les développeurs principaux (dictateurs) et développeurs de confiance (lieutenants) filtrent le code soumis par les développeurs et les utilisateurs indépendants.
Si votre code source change de manière significative, il vous est conseillé de l'expliquer dans la section "pull requests" du forum FreeCAD.
Flux de travail générique pour développer du code pour FreeCAD; Tout le monde peut récupérer le code depuis le dépôt principal, mais les développeurs principaux ont les droits exclusifs pour faire une revue et prendre en compte les changements apportés par les autres développeurs.
Dépôt officiel Github
Une façon simple de commencer à travailler avec le code source de FreeCAD est d'utiliser le dépot officiel FreeCAD
Pour pouvoir contribuer et accéder au code source, vous devez avoir un compte GitHub.
Configuration de votre nom d'utilisateur git
Les utilisateurs doivent faire un commit vers leur dépôt de projet, en utilisant leur nom d'utilisateur GitHub. Si ce n'est pas déjà fait globalement, vous pouvez le régler au niveau local pour le dépôt Git actuel comme ceci :
git config user.name "YOUR_NAME"
git config user.email GITHUB_USERNAME@users.noreply.github.com
dans tous les exemples ci-dessous, "GITHUB_USERNAME" represente votre compte GitHub.
Note sur les dépôts distants
Veuillez lire quelques informations pour vous aider à mieux comprendre la différence entre ce que origin et upstream signifient dans le contexte de git. Cette section explique comment définir les dépôts Git distants en upstream et origin. En gros:
origin
= votre fork du compte git FreeCAD alias https://github.com/GITHUB_USERNAME/FreeCAD.gitupstream
= le dépôt git officiel FreeCAD alias https://github.com/FreeCAD/FreeCAD.git- Ceci est important à comprendre car si vous clonez
git clone
directement à partir de l'upstream
, votre origine sera indiquée comme https://github.com/FreeCAD/FreeCAD.git.
Si vous faites cela accidentellement, vous pouvez utiliser la commandegit remote rename
pour remédier à la situation.
- Ceci est important à comprendre car si vous clonez
La distinction est importante, vous devez d'abord écrire votre code dans votre propre dépôt, avant de "pousser" ces changements sur le dépôt officiel.
En s'appuyant sur ce qui a été dit précédemment, il existe 2 méthodes principales pour configurer votre environnement git:
- 1ère méthode: Créez une branche sur GitHub et clonez votre branche localement
- 2ème méthode: clonez le dépôt officiel de FreeCAD directement sur votre machine locale
Nous recommandons la première méthode car c'est la plus rapide.
1ère méthode: Créez une branche sur GitHub et clonez votre branche localement
Vous allez d'abord créer le référentiel FreeCAD dans GitHub, puis cloner ce fork personnel sur votre ordinateur et enfin définir le référentiel upstream
.
- Log in sur votre compte GitHub.
- Accédez au référentiel officiel FreeCAD:
https://github.com/FreeCAD/FreeCAD
- En haut à droite de la page, appuyez sur le bouton "Fourchette". Cela créera une copie personnelle du référentiel FreeCAD sous votre nom d'utilisateur GitHub:
https: //github.com/GITHUB_USERNAME/FreeCAD
- Sur votre machine, clonez votre nouvelle fourche FreeCAD. Il sera créé dans un répertoire
freecad-source
.
git clone https://github.com/GITHUB_USERNAME/FreeCAD.git freecad-source
- Une fois le téléchargement terminé, entrez le nouveau répertoire source et définissez le référentiel
upstream
.
cd freecad-source
git remote add upstream https://github.com/FreeCAD/FreeCAD.git
- Confirmez vos référentiels distants avec
git remote -v
; la sortie devrait être semblable à celle-ci
origin https://github.com/GITHUB_USERNAME/FreeCAD.git (fetch)
origin https://github.com/GITHUB_USERNAME/FreeCAD.git (push)
upstream https://github.com/FreeCAD/FreeCAD.git (fetch)
upstream https://github.com/FreeCAD/FreeCAD.git (push)
- Maintenant, le développement peut commencer.
2ème méthode: clonez le dépôt officiel FreeCAD git sur votre ordinateur local
Vous allez d'abord créer le référentiel FreeCAD dans GitHub, mais vous clonerez le référentiel FreeCAD d'origine sur votre ordinateur local, puis modifierez vos télécommandes via le terminal.
- Log in sur votre compte GitHub.
- Accédez au référentiel officiel FreeCAD:
https://github.com/FreeCAD/FreeCAD
- En haut à droite de la page, appuyez sur le bouton "Fourchette". Cela créera une copie personnelle du référentiel FreeCAD sous votre nom d'utilisateur GitHub:
https://github.com/GITHUB_USERNAME/FreeCAD
- Clonez le référentiel FreeCAD d'origine. Il sera créé dans un répertoire
freecad-source
.
git clone https://github.com/FreeCAD/FreeCAD.git freecad-source
- Une fois le téléchargement terminé, entrez le nouveau répertoire source et définissez le référentiel
origin
.
cd freecad-source
git remote add origin https://github.com/GITHUB_USERNAME/FreeCAD.git
- Ensuite, configurez le référentiel
upstream
.
git remote add upstream https://github.com/FreeCAD/FreeCAD.git
- Confirmez vos référentiels distants avec
git remote -v
; la sortie devrait être semblable à celle-ci
origin https://github.com/GITHUB_USERNAME/FreeCAD.git (fetch)
origin https://github.com/GITHUB_USERNAME/FreeCAD.git (push)
upstream https://github.com/FreeCAD/FreeCAD.git (fetch)
upstream https://github.com/FreeCAD/FreeCAD.git (push)
- Maintenant, le développement peut commencer.
Si, pour une raison quelconque, les référentiels distants existent mais indiquent une adresse incorrecte, vous pouvez remédier à la situation en renommant le nom du référentiel distant. Par exemple, origin
doit pointer sur votre branche personnelle; s'il pointe vers le référentiel FreeCAD d'origine, remplacez le nom de cette télécommande par upstream
et ajoutez manuellement le référentiel origin
.
git remote rename origin upstream
git remote add origin https://github.com/GITHUB_USERNAME/FreeCAD.git
git remote -v
Vous pouvez également afficher plus d'informations avec le mot clé show
.
git remote show origin
git remote show upstream
Processus de développement Git
Flux de travail générique pour développer du code pour FreeCAD en utilisant git
; Un "fork" du dépôt principal est créé sur le serveur distant et cloné sur un ordinateur local (0); De nouvelles branches (1) sont utilisées pour appliquer des modifications et des ajouts de code localement (2); Les branches sont "rechargées" avec la version de code la plus récente du serveur (3), et elles sont ensuite "poussées" vers le dépôt distant (4); Puis un "Pull Request" est créé afin de pouvoir fusionner le code dans le dépôt principal (5). Le clone du "fork" sur l'ordinateur local est alors mis à jour avec le nouveau code master du serveur (a); Ce master mis à jour est également "poussé" vers le dépôt distant (b) afin d'obtenir le même code à la fois sur le serveur distant et l'ordinateur local.
Ramifications
Une caractéristique importante de Git, est qu'il est extrêmement facile de travailler avec des branches, et, les fusionner. La meilleure pratique recommande de créer une nouvelle branche à chaque fois que vous voulez travailler sur une nouvelle fonctionnalité.
L'ajout d'une nouvelle branche est réalisée en 2 étapes : Tout d'abord vous créez la branche, puis vous commutez sur celle-ci.
git branch myNewBranch
git checkout myNewBranch
ou, les deux opérations en un seule :
git checkout -b myNewBranch
vous pouvez toujours vérifier, dans quelle branche vous êtes avec :
git branch
git branch -vv
Une fois que vous avez effectué les changements et que vous les avez validés (commit), utilisez la ligne de commande log
avec les options suivantes pour visualiser les branches.
git log --oneline --decorate --graph --all
Validation des modifications
Une fois que vous êtes dans une nouvelle branche, éditez les fichiers sources que vous voulez avec votre éditeur de texte. Pour voir quels fichiers ont été modifiés, utilisez la commande status
et diff
; Lorsque que vous êtes satisfait de votre travail, validez le avec la commande commit
:
git status
git diff
git commit -a
Contrairement à SVN, vous devez informer avec précision les fichiers à envoyer (ou la totalité avec l'option -a). Votre éditeur de texte s'ouvrira, pour vous permettre d'écrire un message de validation.
Alternativement, ajoutez le message dans le "commit" lui-même:
git commit -a -m "Fix the bug in the clone function."
Si vous créez de nouveaux fichiers ou répertoires, vous devez d'abord utiliser l'opération add
pour les ajouter au référentiel local avant de valider les modifications.
git add path
git commit -a
Où path
peut être n'importe quel répertoire ou fichier.
Rédaction de bons messages de commit
Vous devriez essayer de travailler en petites sections. Si vous ne pouvez pas résumer vos modifications en une seule phrase, il y a probablement trop longtemps, que vous avez fait un commit.
Pour les grands changements, il est important que vous disposiez de descriptions utiles et utiles de votre travail. FreeCAD a adopté un format mentionné dans le livre Pro Git, qui consiste en un court message, puis en un paragraphe descriptif plus grand.
Court sommaire des changements (50 caractères ou plus)
Si nécessaire, bien détailler les textes explicatifs. Ecrivez-en environ 72 caractères ou plus.
Dans certains cas, la première ligne est considérée comme l'objet (résumé) d'un email, et, le reste du texte comme le corps.
Laisser une ligne blanche pour séparer le résumé, du corps du message (sauf si vous omettez l’entièreté corps);
des outils comme '''rebase''' peut se confondre si vous exécutez les deux ensemble.
Les paragraphes supplémentaires, viennent après les lignes vides.
- Les puces sont très bien aussi
- En général, un trait d'union ou un astérisque est utilisé pour la puce, précédé d'un
espace unique, avec des lignes blanches entre les deux, mais ici les conventions varient.
Si vous effectuez de nombreux travaux connexes dans une branche, vous devez effectuer de nombreux petits commits (voir un forum post) . Lorsque vous souhaitez fusionner ces modifications dans la branche principale, vous devez émettre
git log master..myNewBranch
pour voir les messages individuels de commit. Vous pouvez ensuite écrire un message de haute qualité lors d’une fusion.
Lorsque vous fusionnez pour maîtriser, utilisez l'option --squash
et validez avec votre message de validation de qualité. Cela vous permettra d'être très libéral avec vos commits et vous aidera à fournir un bon niveau de détail dans les messages de validation sans autant de descriptions distinctes.
Regroupement des "commits"
Il est possible de regrouper plusieurs "commits" consécutifs dans 1 seul "commit", on appelle ça le "squashing". Ceci peut être utile dans les cas où vous avez effectué beaucoup de "petits commits" et que vous souhaitez les regrouper dans un seul "commit". Par exemple, lorsque vous changez simplement une variable, que vous corrigez des erreurs d'orthographe ou que vous ajustez la mise en forme de votre code. Vous devez faire des regroupements uniquement sur des "petits commits". Les grandes modifications effectuées sur plusieurs fichiers doivent contenir l'ensemble de l'historique des changements du commit.
Avec la commande git log --oneline
, vous pouvez voir plusieurs "commits" consécutifs dont le plus récent est situé en haut de la liste. Dans cet exemple, plusieurs "commits" ont été effectués à partir de la "fonctionnalité A" pour réaliser l'implémentation de la "fonctionnalité B"; Nous souhaiterions maintenant regrouper tous les "commits" effectués pour la "fonctionnalité B" en un seul.
871adb OK, feature B is fully implemented
1c3317 Whoops, it is not ready yet...
87871a I'm almost ready!
643d0e Code cleanup
af2581 Fix this and that
4e9baa Good implementation
d94e78 Prepare the module for feature B
6394da Feature A
Utilisez la commande rebase
avec l'option --interactive
pour sélectionner différents "commits" et les regrouper en un seul. Utilisez la valeur de hachage située juste devant le premier commit que vous voulez regrouper. Dans notre cas, il s'agit de celui qui correspond à la "fonctionnalité A".
git rebase --interactive 6394da
un éditeur de ligne de commande comme nano
ou vim
s'ouvrira pour vous montrer les "commits", mais cette fois avec le plus ancien en haut de la liste. Avant chaque "commit", le mot pick
sera affiché. Supprimez le mot pick
, et écrivez le mot squash
ou juste la lettre s
à la place, à l'exception de la première entrée; Ce "commit" est le plus ancien, donc tous les futurs "commits" seront regroupés dans celui-ci.
pick d94e78 Prepare the module for feature B
s 4e9baa Good implementation
s af2581 Fix this and that
s 643d0e Code cleanup
s 87871a I'm almost ready!
s 1c3317 Whoops, it is not ready yet...
s 871adb OK, feature B is fully implemented
Sauvegardez le fichier et fermez l'éditeur.
L'éditeur s'ouvrira de nouveau. Vous pouvez maintenant ajouter un long message qui décrira tous les changements effectués comme s'ils étaient réunis dans un seul "commit". Sauvegardez le fichier et fermez l'éditeur une fois de plus. Ceci finira l'action de regroupement de ces "commits" avec le nouveau message que vous avez saisis.
Vous pouvez encore utiliser git log --oneline
pour observer le nouvel historique des changements du commit. Dans ce cas, seul un simple "commit" pour la "fonctionnalité B", apparaitra au dessus du "commit" non modifié pour la "fonctionnalité A".
c83d67 OK, feature B is fully implemented now, with proper module setup, and clean code.
6394da Feature A
Publication de votre travail sur votre dépôt GitHub
Si vous avez un developpement que vous voulez voir intégrer au code source de FreeCAD, veuillez poster une note dans la section Pull Request du forum de FreeCAD
Après avoir fait des modifications sur votre branche locale, et, l'engager (commit) (cela signifie s'engager localement), vous pouvez envoyer votre référentiel sur le serveur. Cela ouvre votre branche au public, et, permet aux principaux développeurs d'examiner, et, d'intégrer votre branche en "maître" .
Pour plus d'informations sur ce sujet, veuillez consulter https://help.github.com/articles/pushing-to-a-remote/
git push origin myNewBranch
Le développeur standard n'a pas d'accès en écriture au référentiel upstream
https://github.com/FreeCAD/FreeCAD
. Par conséquent, vous ne devez pas envoyer de code à ce serveur distant.
Rebasing de l'amont
Pendant que vous travaillez sur votre propre branche, le code officiel de FreeCAD continue de s'améliorer avec les "commits" des autres développeurs, ce qui créé une différence de contenu avec votre branche personnelle.
.-----A origin/myNewBranch / -----o-----------Z FreeCAD upstream/master
Par conséquent, lorsque vous êtes prêt à fusionner votre branche sur le dépôt principal de FreeCAD, vous devez faire un "rebase" (sorte de re-synchronisation) de votre copie du dépôt, afin que son contenu se rapproche le plus possible de celui du dépôt officiel. Voir le document Git Branching - Rebasing pour plus d'informations.
git checkout myNewBranch
git pull --rebase upstream master
Cette opération va télécharger le code à partir de la branche master
du dépôt upstream
(le code source officiel de FreeCAD), et va le fusionner avec celui de votre branche courante (myNewBranch
), afin que vos modifications apparaissent tout en haut de la liste du dernier code officiel. Si personne n'a réalisé de modifications dans les fichiers sur lesquels vous avez travaillés, la fusion se fera sans erreurs. Si certains fichiers ont été modifiés en même temps par des personnes différentes, il se peut qu'il y ait des conflits qui devront être résolus.
.-----A' origin/myNewBranch / -----o-----------Z FreeCAD upstream/master
Pour résumer, vous devez être dans la branche appropriée, faire un "rebase" et puis un "push".
git checkout myNewBranch
git pull --rebase upstream master
git push origin myNewBranch
L'opération pull
est équivalente à un fetch
(récupération) suivit d'un merge
(fusion). Lorsque l'option --rebase
est utilisée, à la place de faire un simple merge
, c'est l'opération rebase
qui sera exécutée.
git pull upstream
git fetch upstream
git merge FETCH_HEAD
git pull --rebase upstream master
git fetch upstream
git rebase master
Fusion de la branche (pull request)
Une fois que vous avez validé vos modifications, "mis à jour" votre branche à partir du dépôt principal et "poussé" votre branche sur le serveur, vous pouvez initier un "pull request". Un "pull request" informe les administrateurs du dépôt officiel de FreeCAD que vous souhaitez fusionner le nouveau code de votre branche avec le code officiel.
As soon as you push the code to your origin
repository https://github.com/GITHUB_USERNAME/FreeCAD
, GitHub will give you the option of comparing and creating a pull request against the upstream
repository. By pressing Compare & pull request 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.
base repository: FreeCAD/FreeCAD base: master <---- head repository: GITHUB_USERNAME/FreeCAD compare: myNewBranch
Able to merge. These branches can be automatically merged.
Click Create pull request 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.
Pull request successfully merged and closed
You’re all set — the GITHUB_USERNAME:myNewBranch branch can be safely deleted.
If you wish, you can also delete your fork of FreeCAD/FreeCAD.
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.
-----o-----------Z----A' FreeCAD upstream/master
Note: you may continue working (git commit -a
) on the same branch while you wait for merge approval; if you git push
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 origin
repository, and this will queue those commits in the same pull request to the upstream
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.
base repository: SomeProject/Some_Software base: master <---- head repository: GITHUB_USERNAME/Some_Software compare: add_new_functions
base repository: GITHUB_USERNAME/FreeCAD base: myNewBranch <---- head repository: FreeCAD/FreeCAD compare: master
base repository: GITHUB_USERNAME/FreeCAD base: myNewBranch <---- head repository: GITHUB_USERNAME/FreeCAD compare: fix-many-bugs-branch
Maintien du dépôt GitHub à jour
Une fois que vous avez créé FreeCAD, votre référentiel personnel existe indépendamment de l'original. Lorsque le référentiel d'origine comporte de nouveaux commits, GitHub vous informera que votre référentiel personnel est en retard sur le nombre de commits:
This branch is 5 commits behind FreeCAD:master.
De la même manière, si vous avez créé une branche de développement avec un nouveau code, GitHub vous informera que cette branche est en avance en nombre de validations; c'est-à-dire que cette branche contient des modifications qui n'ont pas été fusionnées dans le référentiel officiel de FreeCAD:
This branch is 3 commits ahead of FreeCAD:master.
While developing, both cases are possible, as your own branch may lack commits made by other developers, but include new commits by you:
This branch is 2 commits ahead, 14 commits behind FreeCAD:master.
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 master
branch, it will never be automatically updated by GitHub; this is something that you must do yourself. Switch to the master
branch, then pull
from upstream
(which performs a fetch
and merge
), and then push this updated master
branch to your remote origin
repository.
git checkout master
git pull upstream master
git push origin master
After this is done, GitHub will let you know that your are synchronized with the upstream
repository.
This branch is even with FreeCAD:master.
Now that your master
is up to date, you may decide to switch to it, and delete the other branch that you used previously to develop a feature.
git checkout master
git branch -d myNewBranch
To delete the branch in the origin
remote repository, you can use the push
operation. Normally, you push a local branch; this creates a remote branch with the same name as your local branch.
git push origin myNewBranch
However, if you use the notation local_name:remote_name
, the local branch is created in the remote repository under a different name:
git push origin myNewBranch:someRemoteBranch
Therefore, you can delete the remote branch by pushing an empty local branch:
git push origin :myNewBranch
git push origin :someRemoteBranch
Now that you only have an up-to-date master
, you can create a new branch, and repeat the steps of changing files, committing, pushing, submitting a pull request, merging, and updating.
git checkout master
git checkout -b anotherBranch
If you don't want to delete your already custom branch, you may force updating it to be equal to the updated master
; then you can do whatever you want with it, including adding more commits and pushing it to the remote origin
repository.
git checkout myNewBranch
git reset --hard master
git push -f origin myNewBranch
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.
Opérations git avancées
Résolution des problèmes de merge
https://gist.github.com/piscisaureus/3342247
Résolution des conflits de fusion
- explications git-scm sur la manière dont les conflits sont présentés
- Article de GitHub sur la résolution des problèmes de merge par la ligne de commande
- Personnalisez votre outil de merge préféré lorsque vous rencontrez un conflit entre plusieurs git.
La fusion des branches locales via git merge
pourra occasionnellement générer des conflits car les fichiers peuvent être modifiés en même temps et au même emplacement. Si cela se produit, vous allez devoir réparer les fichiers, puis refaire la fusion.
For more information on merging and solving conflicts see:
- How merge conflicts are presented with
git merge
- 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
Inspectez les modifications apportées à un fichier qui a subit plusieurs "commits" :
git log --patch path
Where path
can be any directory or file. Instead of --patch
, also the shorthands -p
or -u
can be used.
Inspect changes between two branches
Inspect the changes between two branches with the log
and diff
operations with the names of the branches:
git log master..myBranch
git diff master..myBranch
The log
operation shows the commits, while diff
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 checkout
operation:
git checkout path
git checkout .
This will restore the path
(a file or a directory) to the state it is at the tip of the branch, discarding changes that haven't been committed. If path
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 clean
operation:
git clean -df
This will forcefully delete all files and directories (-df
) that are not being tracked by the repository, that is, those that have not been included previously with the add
operation.
To completely reset the repository, losing all uncommitted modifications, use the reset
operation:
git reset --hard HEAD
The revert
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 upstream
repository, you may wish to remove these branches from your local system as they have already been merged. The branch in the origin
repository online can be deleted immediately after merging. Then you can remove the local references to that branch, using the --prune
or prune
options to the fetch
and remote
operations.
git fetch --prune origin
git remote prune origin
Finally you can delete the branches locally
git branch -D myBranch
It is also a good practice to do garbage collection after a while, by using the gc
operation. This will cleanup unnecessary files, and compress local file revisions, in order to optimize local disk usage of the repository.
git gc
Working with patches
Bien que Git vous permette de fusionner le code de différentes branches localement sur votre ordinateur via la commande git merge
ou d'effectuer un "pull request" sur le serveur distant (remote repository), il est parfois préférable de créer un patch qui peut être envoyé en tant que pièce jointe par e-mail au lieu de soumettre un PR. Le flux de travail suivant explique comment procéder:
Création de correctifs à partir de Git
- Il est conseillé de travailler dans une nouvelle branche et non pas directement sur la branche master de votre dépôt. La première étape consiste donc à s'assurer que vous êtes dans la bonne branche et le cas échéant à s'y raccorder. Les commandes suivantes permettent de réaliser ces opérations :
git branch -v
git checkout myBranch
- Maintenant, utilisez la commande
git format-patch
et l'option--stdout
pour envoyer le résultat vers la sortie standard STDOUT (Ecran); Le résultat sera ensuite redirigé vers un fichier qui par commodité sera créé dans un dossier de niveau supérieur à celui du code source. (afin de ne pas polluer le répertoire source lui-même, ceci est facultatif car vous pouvez choisir l'emplacement où vous voulez que le patch soit créé)
git format-patch master --stdout > ../myCode.patch
- Une autre méthode consiste à utiliser
git format-patch HEAD^
ougit format-patch HEAD~1
:
git format-patch HEAD^
git format-patch HEAD~1
Le nombre d'accents circonflexes ^
ou le nombre situé derrière le tilde ~ 1
indique le nombre de "commits" qui devront être considérés, à savoir par exemple ^^^
ou ~3
va créer 3 correctifs pour 3 "commits".
git format-patch HEAD^
Cette commande va créer un "patch" ou une série de "patchs" en respectant la convention de nommage suivante :
XXXX-commit-message.patch
où XXXX
est un nombre compris entre 0000
et 9999
, et où le message du "commit" forme la majorité du nom du fichier, par exemple :
0001-fix-ViewProjMatrix-getProjectionMatrix.patch
Application de correctifs via git
Git a la capacité de fusionner des correctifs/diffs. Pour en savoir plus à ce sujet, lisez la référence suivante: Application des patches avec Git
Si vous avez déjà le fichier du correctif dans votre système, il suffit juste de l'appliquer.
git apply myCode.patch
Vous pouvez utiliser curl
pour télécharger un correctif depuis un site web, et ensuite l'appliquer via la commande git
.
curl -O https://some.website.org/code/myCode.patch
git apply myCode.patch
Conseil utile: ajoutez simplement .diff ou .patch à la fin de l'URL d'une page de validation GitHub, d'une demande d'extraction ou d'une vue de comparaison et vous obtiendrez une vue de cette page. Exemple:
- Page GitHub pour un "commit classique" :
https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621
- Page GitHub pour un "Diff" :
https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621.diff
- Page GitHub pour un correctif :
https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621.patch
Vous pouvez pointer curl
vers le "commit" d'un correctif particulier dans un dépôt, et le faire suivre directement vers git
pour appliquer le correctif.
curl https://github.com/FreeCAD/FreeCAD/commit/c476589652a0f67b544735740e20ff702e8d0621.patch | git apply -
Inverser un patch dans git
Si vous avez suivi les instructions ci-dessus et que vous avez changé d'avis, vous pouvez rapidement l'inverser en utilisant:
git apply -R path/file.patch
ou une autre façon est d'utiliser:
git checkout -f
qui supprimera les modifications non validées de la branche
Cette commande annulera les modifications qui ont été appliquées, si vous avez toujours accès au fichier original du correctif :
git apply -R myCode.patch
Cette commande alternative enlèvera toutes les modifications non validées dans la branche :
git checkout -f
Stockage temporaire dans le cache des git commits
Supposons que vous travaillez sur une branche et que vous modifiez la source en dehors du champ de votre branche actuelle. En d'autres termes, il serait préférable d'ajouter certains commits à une autre branche et de les soumettre à la place du fichier actuel. C'est ici que la commande 'git stash' peut être très utile. La commande git stash peut vous aider à stocker (temporairement mais en toute sécurité) vos modifications locales non validées.
git stash
Ensuite, lorsque vous souhaitez utiliser ces commits, vous pouvez faire
git stash apply
ou
git stash pop
pop supprimera le cache
Si vous avez plusieurs caches, vous pouvez faire
git stash list
Pour en savoir plus sur les autres fonctions que vous pouvez utiliser, consultez https://medium.freecodecamp.org/useful-tricks-you-might-not-know-about-git-stash-e8a9490f0a1a
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 git stash
command can be used to temporarily store those uncommitted local changes.
git stash
git stash push
If in the future you want to use those commits, you can pop the commits out of the stash, and into your working branch.
git stash pop
Or if you decide that you don't like those saved commits anymore, you may drop the commits from the stash entirely.
git stash drop
You can list multiple stash commits with
git stash list
To learn more, read Useful tricks you might not know about Git stash.
Check out GitHub requests locally
Checkout GitHub pull requests locally
Numéro de révision FreeCAD
Contrairement à Subversion qui incrémente le numéro de révision, Git génère une valeur de hachage SHA-1 à chaque "commit". Une valeur de hachage est une longue chaîne de caractères alphanumériques qui ressemble à ceci :
9b3ffef570596e184006287434fba54a4b03ccc3
Quelle est la dernière révision de FreeCAD Dev ?
Il y a 2 façons de faire cela:
- 1ère méthode: Dans votre répertoire git cloné, tapez:
git rev-list --count master
git rev-list --count master
git rev-list --count HEAD
git rev-list --count origin
- 2ème méthode: Parcourez le dépôt sur GitHub et lisez le nombre de mises à jour (commits) effectuées dans la branche correspondante.
Quel est le numéro de révision correspondant à la valeur de hachage d'un "commit" ?
Comme la valeur de hachage est une chaîne de caractères alphanumériques, il n'est pas très utile de savoir si un "commit" est plus ancien ou plus récent qu'un autre. Pour trouver le numéro de révision correspond à une valeur de hachage particulière, utilisez à nouveau l'opération rev-list
; l'entrée peut être la valeur de hachage complète ou une valeur de hachage partielle qui est unique, généralement les 7 premiers chiffres sont suffisants.
git rev-list --count ab1520b872821414c6ce4a15fb85d471ac2a2b03
git rev-list --count 9948ee4
Quel est la valeur de hachage correspondante au numéro de révision d'un "commit" ?
Si nous avons un "commit" qui porte le numéro 15000 et que nous voulons trouver la valeur de hachage correspondante, nous allons avoir besoin de calculer le nombre de "commits" réalisés entre ce "commit" et le dernier "commit" (HEAD
). Dans un premier temps, cherchons le numéro du dernier "commit".
git rev-list --count HEAD
17465
Puis, soustrayons à ce résultat le "commit" que nous voulons.
17465 - 15000 = 2465
Puis, utilisez la commande log
pour afficher la liste des "commits" et des valeurs de hachage. L'option --skip
permet de sauter la différence dans les "commits" que nous avons calculez, ce qui nous permet d'aller directement à la valeur de hachage que nous recherchons.
git log --skip=2465
commit 44c2f19e380e76b567d114a6360519d66f7a9e24
Il se peut que le résultat vous affiche 2 "commits" assez proches, confirmez que ce soit le bon numéro de "commit". Si ce n'est pas le cas, choisissez simplement le prochain "commit" dans la séquence (avant ou après) et vérifiez à nouveau.
git rev-list --count 44c2f19e38
15000
Comment le numéro de révision dans l'aide de FreeCAD est-il généré ?
Le numéro de version qui apparait dans Aide → A propos de FreeCAD → Copier dans le presse-papiers est définit dans le fichier src/Build/Version.h
, qui est créé au moment de la compilation lorsque l'outil cmake
est exécuté. Lisez le post Extract version number from git source pour plus d'informations.
Voir la page compilation sur Unix pour avoir les informations complètes sur la compilation de FreeCAD.
Dépôts alternatifs
La force de Git est que tout à chacun peut cloner un projet, et commencer à modifier du code. Plusieurs contributeurs fréquents du projet FreeCAD ont leur propre dépôt Git, avec lequel ils réalisent leur travail avant que des modifications soient prêtes pour être incluses dans le code source officiel, ou avec lequel ils expérimentent simplement de nouvelles idées. Dans certains cas, vous pouvez souhaiter cloner votre code FreeCAD depuis un des ces dépôt plutôt que depuis les dépôts officiels, pour pouvoir bénéficier des changements réalisés par leur utilisateurs.
Il est également possible de lier plusieurs dépôts distants avec un seul code local, en utilisant la commande "git remote". C'est pratique pour rester synchronisé avec la branche "master", mais gardez un œil sur le travail des différents dévelopers.
git remote add Johns_repo https://github.com/John/FreeCAD.git
git remote add FreeCADhacker_repo https://github.com/FreeCADhacker123/FreeCAD.git
Dirigez vous vers la section de développement du forum FreeCAD pour discuter du développement des nouvelles fonctionnalités. Voir aussi la Compilation pour les instructions concernant la compilation de FreeCAD.
Lecture complémentaire
- Développer FreeCAD avec GitKraken, un guide pour utiliser l'interface graphique avec Git.
- Git pour le paresseux, un guide très concis pour les principales commandes de
git
. - Le Pro Git book, un livre open source qui vous apprend à utiliser Git; Il est disponible au format électronique et papier.