Commit 6a8f3f51 authored by Xavier Dolques's avatar Xavier Dolques

Adds help file for newcomers.

parents
==GUIDE D'UTILISATION DE GIT POUR LA RÉDACTION COLLABORATIVE DE PUBLICATIONS==
Vous venez de cloner avec succès le dépot GIT que vous allez utiliser pour rédiger une publication à plusieurs. Vous trouverez dans ce fichier toutes les informations nécessaires pour mettre en place votre environnement de travail. Nous vous présenterons par ailleurs une méthode de gestion de vos versions. Cette méthode n'est sans doute pas parfaite et ne conviendra pas à tout le monde mais nous espérons qu'elle donnera un bon point de départ au débutants avec GIT
Pour commencer, êtes-vous le créateur de la nouvelle publication ou voulez-vous contribuer à une publication déjà existante ? Si vous êtes dans le premier cas lisez à partir de la section 1 ci-dessous, sinon vous pouvez directement aller à la section 2.
1) CRÉATION D'UN NOUVEAU DOCUMENT
GIT permet de prendre une version d'un projet existant et d'en créer une dérivation que l'on nomme "branche" dans le vocabulaire de GIT. Nous allons utiliser cette fonctionnalité pour réutiliser un squelette générique de publication.
Nous proposons un certain nombre de squelettes avec des styles latex couramment utilisés, vous pouvez choisir de partir sur une de ces bases ou sur une base générique. Voici comment :
- Tout d'abord nous allons lister les branches existantes grâce à la commande suivante :
git branch
- Les branches contenant les squelettes ont un nom commençant par "template_". Si vous trouvez le style demandé, il vous suffit de lancer la commande
git checkout <nom du squelette>
où <nom du squelette> est le nom de la branche. Si vous ne trouvez pas votre style, la branche "template_generic" est faite pour vous.
git checkout template_generic
- Vous venez de récupérer le squelette de votre article, vous devez voir dans votre dossier que plusieurs fichiers et dossiers viennent d'être rajoutés. Il ne vous reste plus qu'à créer votre propre dérivation, c'est-à-dire votre propre branche, grâce à la commande suivante :
git checkout -b <nom de la branche>
où <nom de la branche> est le nom que vous donnez à la branche. Vous venez de créer votre branche, votre espace de travail est prêt. Voyez la section 3 pour savoir comment utiliser GIT pour partager cet espace de travail avec vos collaborateurs et gérer les différentes versions de votre article.
2) RÉCUPÉRER UN DOCUMENT DÉJÀ CRÉÉ
Vous venez de cloner un dépôt et vous n'avez accès qu'à ce document. Comment faire pour récupérer la dernière version de l'article qu'un collaborateur a déjà créé et modifié dans ce dépôt ? Un projet d'article correspond à une "branche" dans le vocabulaire GIT. Le dépôt que vous venez de cloner contient plusieurs articles ou squelettes d'article que vous pouvez lister avec la commande
git branch
Vous devriez trouver dans cette liste le nom de la branche qui vous intéresse. Pour récupérer son contenu dans votre répertoire de travail, lancez la commande suivante :
git checkout <nom de la branche>
Vous devriez voir apparaître dans votre dossier de travail la dernière version de l'article de votre collaborateur. Pour participer à la rédaction de cet article, reportez-vous aux sections suivantes.
3) MODIFIER UN DOCUMENT ET SAUVER CES MODIFICATIONS DANS LE DÉPÔT
Cette section n'a pas pour but de vous apprendre à rédiger un article mais à organiser les différentes versions de la rédaction de celui-ci. En effet GIT n'est pas un simple système de partage de fichier, mais il permet de garder un historique de la création d'un projet, historique dans lequel on peut justifier ses modifications et éventuellement y revenir dessus si besoin.
Chaque changement sauvé dans le dépôt GIT va correspondre à une nouvelle version du projet.
Ainsi il est fortement recommandé de créer de nouvelles versions dans le dépôt à chaque changement "unitaire" dans le projet. La définition d'unité de changement est floue, mais si dans votre message décrivant une nouvelle version vous passez par une liste pour décrire vos changements, alors vous pourriez sans doute découper votre sauvegarde en plusieurs bouts.
Il est nécessaire après chaque changement d'indiquer à GIT quels sont ceux que vous souhaitez sauvegarder. Pour rajouter un nouveau fichier ou tous les changements d'un fichier existant on peut passer par la commande suivante :
git add <nom du fichier>
Pour visualiser les changements avant de les ajouter, GIT offre un système intéractif avec la commande suivante :
git add -p
Pour chaque changement (à l'exception des nouveaux fichiers), on choisit s'ils sont à intégrer dans la nouvelle version.
Une fois les changements souhaités sélectionnés, la commande suivante les sauve dans le dépôt :
git commit
Il est nécessaire d'indiquer un message décrivant le changement et il est fortement recommandé de bien le faire pour pouvoir profiter par la suite de la puissance de l'historique GIT. Il est donc recommandé de bien décrire ce qui a été fait et pourquoi. Dans le cas d'un explication plutôt longue, il est d'usage de donner un titre synthétique court dans la première ligne, de sauter une ligne, et de donner tous les détails. Cela permet de tirer partie des navigateurs d'historique qui pour la plupart prennent en compte cette convention pour améliorer leur interface.
Notez que les modifications que vous venez d'apporter viennent d'être sauvées dans votre dépôt local, c'est-à-dire que vous êtes pour le moment le seul à y avoir accès. Nous allons donc voir dans la section suivante comment partager vos modifications avec le reste de vos collaborateurs.
Conseils :
- Les modifications dans les fichiers sont considérées par ligne, c'est -à-dire qu'un caractère modifié dans une ligne sera traité par GIT de la même manière que si toute la ligne est modifiée. Ainsi il est déconseillé de faire des lignes trop longues pour pouvoir suivre les modifications dans un texte avec précision. En LaTeX, le passage à la ligne simple n'a pas de conséquence sur la mise en forme, nous conseillons donc un maximum d'une phrase par ligne.
- Nous insistons sur la nécessité de garder un historique le plus "propre" possible pour profiter de toute la puissance de GIT. Ainsi nous vous conseillons de bien structurer vos nouvelles versions avant de les partager, car elles deviennent très difficiles à modifier une fois partagées. Les utilisateurs les plus à l'aise trouveront à cette adresse de nombreux conseils pour améliorer leurs projets :
http://www.git-attitude.fr/2014/05/04/bien-utiliser-git-merge-et-rebase/
4) RÉCUPÉRER LES MODIFICATIONS DES AUTRES ET PARTAGER SES PROPRES MODIFICATIONS
Nous allons voir ici comment partager ses modifications avec ses collaborateurs. Comme nous parlons de modifications concurrentes, il est nécessaire de s'assurer que nous ayons bien la dernière version partagée du projet avant de proposer de nouvelles modifications.
Avant de récupérer les dernières versions il faut s'assurer que toutes vos modifications sont sauvées dans votre dépôt
git status
Sauvez ce que vous souhaitez. Si vous ne souhaitez pas tout sauvegarder (par exemple si vous n'avez pas fini vos changements), vous pouvez stocker les modifications non validées dans un espace temporaire en faisant
git stash
Ces modifications disparaissent alors de vos fichiers, pour les récupérer par la suite, faites
git stash pop
Pour récupérer les dernières version à partir du dépôt distant on utilise la commande suivante :
git pull --rebase=preserve origin <nom de la branche>
GIT va alors récupérer les dernières versions du projet et les rajouter dans votre dépôt AVANT vos propres modifications. Il va ensuite essayer de rajouter dessus vos modifications. Si cela devait mal se passer, c'est-à-dire si vos modifications se font sur des parties qui viennet d'être récupérées, GIT vous guidera pour régler le conflit.
Une fois votre dépôt à jour, vous pouvez envoyer vos nouvelles versions sur le dépôt distant grâce à la commande suivante :
git push origin <nom de la branche>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment