Gerrit/outil git-review
git-review est un outil en mode ligne de commande pour Git / Gerrit permettant de soumettre une modification, ou de récupérer une modification existante.
Notez que Wikimedia Gerrit nécessite la version 1.27 ou supérieure de git-review.
La branche principale du projet est gérée par OpenStack. A ne pas confondre avec le projet Facebook qui est indépendant.
Installation
- Voir aussi : tutoriel Gerrit
Après avoir installé Git (1, 2), créé un compte utilisateur Gerrit, créé une clé ssh (3, 4), et cloné le dépôt de votre projet (ou celui de l'exemple), vous êtes prêt à installer git-review, un outil pour travailler avec les dépôts Gerrit qui vous évite de mémoriser les commandes correspondantes. Suivez les instructions ci-dessous en fonction de votre système d'exploitation, et n'oubliez pas de le configurer ensuite !
Linux
Debian/Ubuntu/Mint
Les utilisateurs de Debian ou des distributions associées (telles que Ubuntu, Mint) sur un hôte partagé n'ont habituellement pas l'accès root. Si l'administrateur de votre site d'hébergement ne peut pas vous installer git-review, vous pouvez essayer de le faire localement. Allez à la section correspondante ci-dessous.
Avec un accès root
Vous pouvez faire :
sudo apt-get install git-review
ou :
sudo apt-get install python-pip
sudo easy_install pip
sudo pip install git-review
Si vous ne disposez pas de easy_install, essayez :
sudo apt-get install python-setuptools
Si vous n'avez pas apt-get mais que python est installé, vous pouvez utiliser ceci (voir plus loin pour les instructions particulières pour OS X) :
sudo easy_install pip
sudo pip install git-review
Si vous avez Ubuntu 20.04, essayez :
sudo apt-get install python3-pip
sudo pip3 install git-review
Puis exécutez :
git review -s
dans votre copie clonée, pour configurer votre environnement de travail Gerrit. On vous demandera probablement votre nom d'utilisateur pour la validation. L'accroche commit-msg sera ensuite automatiquement installée.
Sans accès root
Si vous êtes sur un hôte partagé et que votre système n'a pas git-review, vous pouvez l'installer localement dans votre répertoire utilisateur.
virtualenv --python=/usr/bin/python2.6 virtualenv
virtualenv/bin/pip install git-review
Si ceci est votre première installation locale, ou si vous ne l'avez pas encore fait, mettez à jour votre variable d'environnement PATH pour prendre en compte les binaires locaux. Il y a deux manières de faire cela. La manière la plus conservative :
PATH=$PATH:~/virtualenv/bin/
laisse le système chercher d'abord parmi les répertoires des binaires, et ne consulte le répertoire local des binaires que si la commande n'a pas été trouvée auparavent. Si vous voulez que le logiciel installé localement dans votre répertoire home prévale sur les programmes du système, vous devez inverser l'ordre d'exploration.
PATH=~/virtualenv/bin/:$PATH
Vous avez peut-être déja fait cela plus tôt. Vous pouvez ajouter la commande de votre choix à votre séquence de connexion pour qu'elle s'exécute automatiquement.
Si vous ne voulez pas modifier votre variable PATH vous n'y êtes pas obligé. Dans ce cas, vous ne pouvez pas utiliser la commande git review mais utilisez ~/virtualenv/bin/git-review à la place.
Exécutez enfin :
git review -s
ou
~/virtualenv/bin/git-review -s
respectivement, dans votre copie clonée pour le configurer afin qu'il fonctionne avec Gerrit. On vous demandera probablement votre nom d'utilisateur pour la validation. L'accroche commit-msg sera ensuite automatiquement installée.
Fedora≤21/CentOS
sudo yum install git-review
Si pendant l'utilisation de git-review vous voyez ImportError: No module named requests, vous devrez installer python-requests :
sudo yum install python-requests
Il est possible que yum ne trouve pas le paquet git-review -- dans ce cas vous pouvez autoriser le répertoire EPEL et recommencer.
Fedora≥22
sudo dnf install git-review
OpenSUSE
Installez (YaST) le python-setuptools, ensuite :
easy_install pip
pip install git-review
Depuis OpenSUSE 13.1, git-review se trouve dans le dépôt principal, vous pouvez donc utiliser :
sudo zypper in git-review
Gentoo
emerge dev-python/git-review
Arch Linux
Arch ne dispose pas de git-review dans les dépôts mais possède un PKGBUILD dans le AUR :
git clone https://aur.archlinux.org/git-review.git
cd git-review
makepkg -s
sudo pacman -U <resultingpackage>
NixOS (ou n'importe quel Linux avec Nix installé)
git-review est disponible en tant que paquet dans les branches stable et instable de nixpkgs. Essayez-le en ouvrant un shell où git-review est disponible :
Stable
nix run -f channel:nixos-21.05 git-review # adjust to your release
Instable
nix run -f channel:nixos-unstable git-review
Faites l'installation selon votre méthode préférée (votre propre gestionnaire, ou via la configuration du système ou encore avec nix-env).
Installation avec l'installateur du paquet Python pip
Note: si apt-get n'est pas installé mais que python l'est, vous pouvez également installer la dernière version de git-review en utilisant l'installateur de paquets Python.
La commande exacte dépend de votre distribution, soit :
sudo apt-get install python-pip
ou
sudo easy_install pip
Une fois pip installé, vous pouvez utiliser :
sudo pip install git-review
FreeBSD
Vous pouvez directement installer git-review par les ports.
cd /usr/ports/devel/git-review
make install
Windows
Il faut Python pour que git-review fonctionne et pip sert à l'installer :
- Installez Python ou mettez à jour avec la version la plus récente de Python 2 ou Python 3.
- Important: n'installez pas Python dans un dossier où il y a un espace dans l'expression du chemin car cela pose un problème dans pip (voir [1]), utilisez la valeur par défaut, c'est à dire
C:\Python34\ - Durant l'installation de Python, sélectionnez manuellement « Add python.exe to Path » pour ajouter l'exécutable python à la variable d'environnement Path.
- Sinon ajoutez vos répertoires de scripts Python manuellement parmi les chemins système (Menu→Paramètres→Panneau de contôle→Système→Paramètres système avancés→Variables d'environnement→Variables utilisateur→Path; par exemple
C:\Python34\;C:\Python34\Scripts\;). Dans PATH, les différents répertoires sont séparés uniquement par un point-virgule;- n'ajoutez aucun espace à la liste des chemins. - Python 3.4 possède déjà pip installé. Seulement si vous avez une version plus ancienne, installez pip en suivant ces instructions.
- Exécutez Git Bash en tant qu'administrateur (cliquez-droit sur l'icône pour voir cette option) et installez git-review à l'aide des commandes suivantes :
pip install git-review
- Si vous avez des problèmes comme par exemple :
Retrying (Retry(total=4, connect=None, read=None, redirect=None)) after connection broken by 'ConnectTimeoutError(<pip._vendor.requests.packages.urllib3.connection.VerifiedHTTPSConnection object at 0x03B55750>, 'Connection to pypi.python.org timed out. (connect timeout=15)')': /simple/git-review/
- essayez d'exécuter :
pip install git-review --proxy=www-proxy-lon.uk.oracle.com:80
- le proxy à utiliser exactement peut être extrait du fichier http://wpad/wpad.dat .
- Pour utiliser
git review, vous devez être dans un répertoire cloné de Git qui contient déjà un fichier de configuration.gitreviewéventuellement caché (voir Configurer un dépôt pour Git distant)
Mac OS X
Méthode 1 (Homebrew)
Fonctionne sous OS X 10.11 El Capitan et ultérieur (vérifié sous High Sierra 10.13.5) :
- Installer Homebrew
- Installer git-review avec
brew install git-review
Méthode 2 (paquet Python de l'installateur pip)
Mac OS X est livré avec Python 2.7 (jusqu'à présent) mais sans les programmes d'installation pris en charge par Git et git-review.
- Ouvrez une fenêtre Terminal et placez-vous dans un répertoire pour y télécharger les paquets de test Git (par exemple Téléchargement)
- Téléchargez et installez l'installeur OS X pour Git (pour OS X 10.8 et antérieur uniquement; OS X 10.9 est livré avec Git préinstallé)
- Installez pip (déjà présent dans certaines anciennes versions de OS X) :
sudo easy_install pip
- Mettez à jour pip/setuptools (pour OS X 10.7 et antérieur uniquement) :
sudo pip install -U setuptools
- Installez git-review. Depuis la version « El Capitan » , OS X protège les emplacements du système de fichiers y compris
/System/Library/Frameworks/Python.framework/Versions/2.7/share, donc la méthode d'installation habituelle utilisant sudo va échouer. A la place, vous installerez git-review localement dans votre répertoire home de la manière suivante :pip install --user git-review
- Mettez à jour votre variable d'environnement PATH pour inclure le chemin vers git-review qui doit être dans
$HOME/Library/Python/2.7/bin
Si vous obtenez l'erreur pkg_resources.DistributionNotFound: git-review, vous pouvez essayer de supprimer le Python préinstallé (/Library/Python/), en installant Python via homebrew (brew install python), puis en réinstallant setuptools et git-review.
Si vous obtenez un message git command not found après que l'installation ait à priori réussi, n'essayez pas de réinstaller par dessus l'existant, mais désinstallez git-review et refaites
sudo pip install -U setuptools
Configurer git-review
Suivez les instructions du tutoriel Gerrit pour configurer git-review de sorte à ce qu'il utilise « origin » comme étant le distant par défaut. Ceci évite la confusion et les conflits entre des distants nommés gerrit et origin.
Après avoir cloné un dépôt, vous devez le paramètrer pour utiliser git-review. Ceci se fera automatiquement la première fois que vous essayerez de soumettre une validation, mais il est généralement mieux de le faire juste après avoir cloné.
cd MyNewProj
git review -s
On pourra vous demander votre nom d'utilisateur git, s'il diffère du nom de l'utilisateur du shell que vous utilisez.
En interne, voici ce qui se passe :
- il vérifie si l'accès au dépôt distant est possible
- si ce n'est pas le cas, il demande un nom d'utilisateur et renouvelle l'essai
- il crée un distant appelé 'gerrit' qui pointe sur gerrit
- il installe l'accroche commit-msg
Publier les modifications avec git-review
Soumettre des modifications avec git-review n'implique que très peu de commandes :
git checkout -b mycoolfeature [change files] git commit -a git review
Ce qui se passe quand vous publiez vos modifications
Lorsque vous soumettez une modification, git-review réalise les actions suivantes :
- il cherche dans le fichier .gitreview la branche à pousser (production ou autre). S'il ne peut pas trouver cette information, il pousse sur le master.
- il extrait le titre à attribuer à la révision (vous pouvez définir le sujet manuellement avec
-t)- si vous soumettez à nouveau une modification téléchargée, il reprendra le titre de la modification originale
- si le résumé de votre modification contient un numéro de bogue tel que
bug 12345, le titre serabug/12345 - sinon, le titre sera le nom de votre branche locale
- il fait un rebase de vos modifications sur la tête (HEAD) de la branche sur laquelle vous poussez (utilisez
-Rpour sauter cette étape) - si vous soumettez plus d'une correction à la fois, ou si vous soumettez une modification basée sur une autre modification qui n'a pas été fusionnée, il vous sera demandé si vous voulez réellement faire cela (utilisez
-ypour sauter cette étape) - il pousse la modification pour relecture.
Modification du travail en cours
If you want to share an unfinished change (for example to ask help on how to solve a problem), you can use the --work-in-progressoption to mark the patch as WIP (you can filter out such patches in Gerrit searches using -is:wip):
git review --work-in-progress
It's best practice to also prefix the commit summary with [WIP] when doing that.
Télécharger une modification avec git-review
Lorsque vous téléchargez une modification à partir de gerrit pour la relire ou pour l'amender, git-review offre une alternative pour copier/coller une incantation magique à partir de l'interface utilisateur web Gerrit.
Tout ce dont vous avez besoin, c'est le numéro de séquence de la modification dans Gerrit, que vous pouvez trouver dans l'URL : https://gerrit.wikimedia.org/r/2033.
git review -d 2033
Ceci va télécharger la modification, la placer dans une branche appelée review/AUTHOR/TAG (si la modification n'a pas d'étiquette, le numéro de séquence sera utilisé à la place) et qui deviendra la branche courante.
Après cela, vous pouvez amender la modification téléchargée afin de l'améliorer.
Alternatively, you can use git review -x 2033 to download (cherry-pick) the patch into the current branch.
Résolution des problèmes
Pour les problèmes et la manière de les résoudre, voir Gerrit/Troubleshooting.
Sous Windows
Si cela ne fonctionne pas, il existe plusieurs possibilités. D'abord il faut utiliser scp (secure copy) à partir du répertoire local correspondant à chacun de vos dépôts, avant de valider les modifications à l'intérieur :
scp -P 29418 USERNAME@gerrit.wikimedia.org:hooks/commit-msg .git/hooks/commit-msg
Ensuite il faut essayer de patcher c:\Python27\Scripts\git-review pour que git-review fonctionne correctement :
--- /c/Python27/Scripts/git-review-old Tue May 28 20:51:50 2013
+++ /c/Python27/Scripts/git-review Tue May 28 20:48:03 2013
@@ -952,6 +952,9 @@
config = get_config(os.path.join(top_dir, ".gitreview"))
hook_file = os.path.join(git_dir, "hooks", "commit-msg")
+ # msysgit hacks to work around scp.exe (--aaron)
+ hook_file = unicode.replace( ".\%s" % os.path.relpath( hook_file ), "\\", "/" )
+
defaultrebase = convert_bool(
git_config_get_value("gitreview", "rebase",
default=str(config['defaultrebase'])))
Si vous utilisez Python 2.x et git-review 1.17 ou antérieur, utilisez str.replace au lieu de unicode.replace.
Une autre erreur rencontrée sous Windows est :
...
(top_dir, git_dir) = git_directories()
ValueError: too many values to unpack (expected 2)
Une solution pour cela est de modifier la ligne retournée de git_directories() et d'utiliser les splitlines plutôt que la fonction normale split.
Split recherche les espaces et génère cette erreur quand le chemin de votre répertoire de code source contient un espace.
Splitlines recherche les caractères de passage à la ligne et ne produit pas cette erreur.
return out.splitlines()