LisezMoi.txt 9.4 KB
Newer Older
Xavier Dolques's avatar
Xavier Dolques committed
1 2 3 4 5 6 7 8
==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

9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28
1.1) CONNEXION AU BON DÉPÔT

Vous venez de clôner un dépôt, mais celui-ci correspond-il au dépôt de travail pour votre publication ou s'agit-il d'un dépôt contenant seulement les squelettes de publication ? Si il s'agit du dépôt de travail vous pouvez passer directement au 1.2, sinon suivez les instructions qui suivent.

Votre dépôt est lié au dépôt que vous venez de cloner grâce à son adresse, ce dépôt distant à pour identifiant "origin". Ce lien implique que par défaut git ira récupérer depuis (fetch) ou enverra des données vers (push) origin. Vous pouvez le visualiser en tapant la commande suivante :

git remote -v

Ce lien doit être modifié pour que origin pointe vers votre dépôt de travail. Cela nécessite que le dépôt de travail existe, pour cela allez sur l'interface web de votre forge et créez un nouveau projet. Récupérez l'adresse de ce nouveau projet, et changez le lien d'origin grace à la commande suivante :

git remote set-url origin <adresse du nouveau dépôt>

L'adresse du dépôt est l'adresse qui vous est généralement proposée pour cloner le projet. Une fois le lien établi vous pouvez transférer tout le contenu du dépôt via la commande :

git push origin --all

Vous avez désormais un lien vers le bon dépôt, vous pouvez désormais créer une branche pour votre nouvelle publication.

1.2) CRÉATION D'UNE NOUVELLE BRANCHE POUR LA PUBLICATION

Xavier Dolques's avatar
Xavier Dolques committed
29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
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>