Maxime "zaz" Montinet zaz@epitech.eu Abstract: Ce document decrit la marche a suivre pour utiliser les rendus par systeme de controle de versions utilises au cours des differents modules geres par le Koalab
Table des matières I Avant toute chose 2 I.1 Notes importantes.............................. 2 I.2 Version courte................................. 3 I.2.1 FAQ.................................. 4 II Cle SSH 6 II.1 Enregistrement sur koala-rendus....................... 6 II.2 Mise en place pour l utilisation....................... 7 II.2.1 BSD/Linux.............................. 7 II.2.2 Windows................................ 7 III SVN 9 III.1 BSD/Linux.................................. 9 III.2 Windows................................... 9 IV Mercurial 10 IV.1 BSD/Linux.................................. 10 IV.2 Windows................................... 10 V Git 12 V.1 BSD/Linux.................................. 12 V.2 Windows................................... 12 1
Chapitre I Avant toute chose N ATTENDEZ PAS LE DERNIER MOMENT pour recuperer votre depot et commencer a travailler dessus! Ainsi, si d aventure vous avez un souci, vous aurez tout votre temps pour le resoudre. Notez que les personnes qui viennent demander de l aide le dernier jour, 1h avant le rendu, se heurtent generalement a un "Fallait y penser avant!", qui est d ailleurs justifie... I.1 Notes importantes Ce guide presume que vous connaissez le nom du depot que vous cherchez a utiliser. Dans tous les cas, la forme du nom d un depot est <nom du projet>-<promo>-<login du leader>. (Vous recevrez generalement un e-mail au moment ou les depots de votre projet sont disponibles, qui vous precisera le nom du depot. Cet e-mail n est en general addresse qu aux chefs de groupes.) Ce guide presume egalement, dans TOUS LES CAS sous BSD/Linux, que votre cle privee SSH se trouve dans ~/.ssh/id_rsa, et est donc la cle utilisee par defaut par SSH. On presume egalement que si vous utilisez des outils type ssh-agent, vous savez vous en servir! (ssh-add, tout ca...) Ce guide presume enfin que vous savez vous servir de git, svn, et mercurial, et que vous avez les moyens de recuperer votre cle SSH du PIE avec Windows (WinSCP, ou alors monter l AFS). Dans le cas contraire, ce guide presume que vous savez lire une documentation... Ce guide explique, pour chaque SCM propose par le Koalab, la marche a suivre pour se connecter a un depot a l aide des outils svn, hg et git en ligne de commande sous BSD/ Linux, ainsi que TortoiseSVN, TortoiseGit et TortoiseHg sous Windows. Tout autre utilitaire ne fera pas l objet d une documentation et son utilisation se 2
fera a VOS risques et perils. Veillez donc a vous conformer a ce guide si vous n avez pas envie d experimenter. Vous etes prevenus. Ce guide et tous les outils qu il utilise ont ete testes avec succes sur les dumps etudiant, et de facon plus generale sur Windows XP/Vista/Seven (32 et 64 bits), FreeBSD/Debian/Archlinux/Fedora/Ubuntu (32 et 64 bits). Veuillez egalement noter que dans le cas ou vous avez plusieurs depots pour un meme projet, les depots sont DIFFERENTS. Ils NE sont PAS repliques entre les differents SCM. Vous devez donc CHOISIR un SCM, et ne pas en utiliser plusieurs a la fois... Ne voyez pas l utilisation d un systeme de controle de versions comme une corvee. C est important pour votre futur en tant que developpeur de savoir vous en servir. Accessoirement, si vous prenez la peine de lire quelques tutoriaux et d apprendre a vraiment les utiliser, c est extremement pratique pour coder a plusieurs sur vos projets. Enfin, je vous en SUPPLIE, je vous IMPLORE... Lisez les documentations des SCM que vous utilisez! Ca ne prend pas longtemps de lire un tutorial, et ca vous evitera bien des maux de tetes! I.2 Version courte Pour ceux qui savent deja utiliser SVN/Git/Mercurial en SSH et qui n ont pas envie de lire 20 kilometres de doc... Rendez vous sur http://koala-rendus.epitech.net. Authentifiez vous a l aide de votre mot de passe PPP (intra), et utilisez le formulaire qui vous est presente pour uploader votre cle SSH publique. Attendez 10 minutes que votre cle SSH soit propagee sur le systeme. Allez boire un cafe, par exemple. Recuperez votre depot qui se trouve, selon le SCM, sur : svn+ssh://kscm@koala-rendus.epitech.net/nomduprojet-promo-login_chef (Pour SVN) ssh://kscm@koala-rendus.epitech.net/nomduprojet-promo-login_chef (Pour Hg) kscm@koala-rendus.epitech.net:nomduprojet-promo-login_chef (Pour Git) 3
I.2.1 Profit. Si vous n y arrivez pas... tant pis, lisez le reste, merci! FAQ Si vous etes CERTAINS d avoir tout fait comme demande par cette documentation, et que votre probleme persiste, la solution est peut-etre bien la. Problemes ponctuels Durant la periode mars/avril 2011 a eu lieu la migration des services de rendus du Koalab depuis koala-scm.epitech.net vers koala-rendus.epitech.net. Si votre projet est sur koala-rendus (Comme precise par le mail que vous avez du recevoir), vous devez egalement uploader vos cles ssh sur koala-rendus et non plus koala-scm. Ce n est PAS le meme serveur. Problemes avec l enregistrement de la cle SSH : Mauvais mot de passe utilise. Utilisez votre pass PPP (= mot de passe intranet!). Si vous n arrivez pas a faire accepter votre mot de passe (apres plusieurs essais!), envoyez votre cle publique par mail a zaz@epitech.net. Envoi d une cle PuTTY (format.ppk). Utilisez une cle OpenSSH. Envoi d une cle trop courte (<2048b). Utilisez "ssh-keygen -b 2048". Causes frequentes de problemes de connection au depot en lui-meme : Cle SSH non propagee sur koala-rendus : Attendez 10 minutes, puis reessayez. Cle SSH non prise en compte par ssh-agent. Tapez "ssh-add" dans un terminal, puis reessayez. Cle SSH avec des droits trop laxistes. Mettez les permissions 600 sur ~/.ssh/id_rsa et 644 sur ~/.ssh/id_rsa.pub, puis reessayez. Utilisation des depots depuis l AFS au mauvais moment... Utilisez votre depot en local! Autres Si vos problemes persistent (Impossible de joindre le depot), tentez un "ssh kscm@koala-rendus.epitech.net". Cela ne fera rien de concret, mais le message d erreur sera probablement plus verbeux et vous permettra de trouver plus facile- 4
ment votre erreur. "ssh -vvvv" donnera un log de debug colossal mais qui peut aider a saisir le probleme. Si vous envoyez un mail pour de l aide, pensez a inclure les choses suivantes (Car on vous les demandera de toute facon!) Votre login et promo exacte Les commandes que vous utilisez et leur sortie (Une copie de votre terminal fera l affaire) 5
Chapitre II Cle SSH II.1 Enregistrement sur koala-rendus Cette operation n est a faire qu une fois par cle differente que vous possedez! Ce n est ABSOLUMENT PAS la peine de re-uploader votre cle toutes les 5 minutes. Le seul cas ou vous devriez avoir besoin de re-uploader une cle sur le systeme est le cas ou vous changez de cle. Rendez vous sur http://koala-rendus.epitech.net. Authentifiez vous a l aide de votre mot de passe PPP (intra). Utilisez le formulaire qui vous est presente pour uploader votre cle PUBLIQUE. Pour creer une cle SSH (sur le PIE) : Se loguer, taper ssh-keygen, choisir un emplacement de sauvegarde (Par defaut ~/.ssh), et une passphrase (eventuellement). La cle privee est ~/.ssh/id_rsa, la cle publique est ~/.ssh/id_rsa.pub. C est cette derniere que vous devez uploader. Si le systeme d enregistrement vous dit que votre cle est invalide, ouvrez votre cle sous vim ou autre et verifiez : Si elle ne commence pas par "ssh-rsa" ou "ssh-dss", elle est invalide. Je pense notemment a ceux qui ont uploade une cle au format.ppk (Cle PuTTY) : Ces dernieres NE MARCHERONT PAS. Le systeme refusera egalement les cles RSA d une longueur inferieure a 2048 bits (Longueur par defaut sur le PIE. En cas de probleme, forcer la longueur avec "ssh-keygen -b 2048") 6
II.2 Mise en place pour l utilisation II.2.1 BSD/Linux Assurez vous simplement que la cle SSH privee associee a la cle publique que vous avez enregistre sur notre serveur soit : ~/.ssh/id_rsa (C est le cas par defaut.) II.2.2 Windows Vous aurez besoin des outils suivants : WinSCP putty plink pageant puttygen Commencez par utiliser WinSCP ou assimile pour recuperer votre cle SSH privee. (Vous pouvez egalement monter l AFS, voir intra-bocal) Ouvrez ensuite puttygen, allez dans le menu Conversions, et selectionnez votre cle privee. Cliquez ensuite sur "Save private key", et sauvegardez la sur votre disque. A partir de maintenant, chaque reference a votre "cle privee" sera une reference a la cle que vous venez de sauver (format.ppk). Ensuite, deux solutions : Pageant Lancez pageant. Double cliquez sur l icone de pageant dans le systray pour ouvrir l interface, cliquez sur Add key, et selectionnez votre cle privee. Le soft se servira automatiquement de cette cle quand vous interagirez avec le depot. Par contre, si vous partagez le PC avec un binome, ca devient plus problematique, car Pageant utilisera la premiere cle qui marche avec le depot selectionne, et vous serez donc toujours authentifie en tant que la personne proprietaire de ladite cle. A n utiliser donc que si vous etes seul sur la machine. Lancer pageant au demarrage avec un script batch en lui passant des cles a utiliser en ligne de commande, ca marche... PuTTY Lancez putty, puis remplissez les champs suivants : Session > Host Name : koala-rendus.epitech.net Session > Connection Type : SSH 7
Connection > Data > Auto-login username : kscm Connection > SSH > Auth > Private key file for authentication : <votre cle privee> Retournez dans la page Session, entrez un nom dans le champ sous Saved Sessions (par exemple kscm_koala_login_x), puis cliquez sur Save. Ensuite, au lieu d utiliser kscm@koala-rendus.epitech.net pour vous connecter, vous utiliserez le nom de la connection que vous venez de creer, et le soft utilisera les parametres que vous avez choisi. Cette solution permet de sauvegarder autant de reglages que vous voulez, si vous etes plusieurs a partager la machine 8
Chapitre III SVN III.1 BSD/Linux Checkout le depot : 1 zaz@naqadah:~/scm/$ svn checkout svn+ssh://kscm@koala-rendus.epitech.net/test -2011-montin_m 2 Checked out revision 0. 3 zaz@naqadah:~/scm/$ cd test-2011-montin_m 4 zaz@naqadah:~/scm/test-2011-montin_m$ Travaillez ensuite normalement sur votre depot. III.2 Windows Vous aurez besoin de TortoiseSVN. Pour checkout votre depot SVN, cliquez droit dans un dossier, puis SVN Checkout. Dans URL of repository, entrez : svn+ssh://kscm@koala-rendus.epitech.net/<nom DU REPO> (ou svn+ssh://nom_de_la_connection/<nom DU REPO> si vous n utilisez pas Pageant), puis cliquez sur OK. Travaillez ensuite normalement sur votre depot. 9
Chapitre IV Mercurial IV.1 BSD/Linux Clonez le depot : 1 zaz@naqadah:~/scm/$ hg clone ssh://kscm@koala-rendus.epitech.net/test-2011- montin_m 2 destination directory: test-2011-montin_m 3 requesting all changes 4 adding changesets 5 adding manifests 6 adding file changes 7 added 1 changesets with 1 changes to 1 files 8 1 files updated, 0 files merged, 0 files removed, 0 files unresolved 9 zaz@naqadah:~/scm/$ cd test-2011-montin_m 10 zaz@naqadah:~/scm/test-2011-montin_m$ Travaillez ensuite normalement sur votre depot. IV.2 Windows Vous aurez besoin de TortoiseHg. Pour cloner votre depot Mercurial, cliquez droit dans un dossier, puis TortoiseHg > Clone a repository. Dans "Source path", entrez : ssh://kscm@koala-rendus.epitech.net/<nom DU REPO>, puis cliquez sur Clone. Travaillez ensuite normalement sur votre depot. Note IMPORTANTE : N oubliez surtout pas, pour synchroniser VOTRE depot avec NOTRE depot, de pusher vos changements sur le serveur. Pour ce faire, clic droit dans votre depot, puis TortoiseHg > Synchronize, puis cliquez sur Push. 10
Lors de votre soutenance, c est NOTRE depot qui fait foi : Si vous n avez pas push votre travail, tant pis pour vous. 11
Chapitre V Git V.1 BSD/Linux Clonez le depot : 1 zaz@naqadah:~$ git clone kscm@koala-rendus.epitech.net:test-2011-montin_m 2 Initialized empty Git repository in /home/zaz/test-2011-montin_m/.git/ 3 warning: You appear to have cloned an empty repository. 4 zaz@naqadah:~$ cd test-2011-montin_m/ 5 zaz@naqadah:test-2011-montin_m$ Comme lors de votre premier push il n y a aucune branche sur le depot distant, vous devez selectionner la branche master de facon explicite en utilisant : 1 zaz@naqadah:~$ git push origin master Une fois cela fait, vous pourrez faire des push simples : 1 zaz@naqadah:~$ git push Veuillez noter qu a la soutenance, nous corrigerons la branche "master", et pas une autre. V.2 Windows Vous aurez besoin de TortoiseGit, qui depend de MSysGit. Vous pouvez trouver MSysGit sur http://code.google.com/p/msysgit/downloads/ list (Utilisez le premier download, "Official Git", et non pas le download nomme MSys- Git...) Faites bien attention lors de l installation a choisir l option "Run Git from Command line" et non pas "Use Git Bash only", sinon TortoiseGit ne fonctionnera pas. Si vous avez 12
envie d utiliser Git en ligne de commande et non pas forcement depuis Tortoise, choisissez egalement d utiliser PLink et non OpenSSH lors de l installation. Une fois TortoiseGit installe et configure (Clic droit > TortoiseGit > Settings, dans MSysGit path entrer C :\Program Files\Git\bin, ou le dossier bin du repertoire d install de Git), vous pouvez commencer. Pour cloner le depot, clic droit > Git Clone, et dans Url, entrez : kscm@koala-rendus.epitech.net:< DU REPO> Note IMPORTANTE : N oubliez surtout pas, pour synchroniser VOTRE depot avec NOTRE depot, de pusher vos changements sur le serveur. Pour ce faire, clic droit dans votre depot, puis TortoiseGit > Push. Lors de votre soutenance, c est NOTRE depot qui fait foi : Si vous n avez pas push votre travail, tant pis pour vous. 13