plain-html-redo/README.md

# Accéder au projet :
( va afficher le contenu du dossier "/public" )   

URL du projet perso          
- https://USERNAME.gitlab.io/PROJECT_NAME   
=>    
EX/ mon projet (fork)    
L'URL FINALE == https://bonnebulle.gitlab.io/plain-html-redo    
Redirige vers = https://plain-html-redo-751743.gitlab.io    
( URL Non personelle )    
. . .   
mais hébergement gratuit !   

---

# Tuto :    

## Objectif :     
Cloner un projet initial existant
( "> git clone +url" )   
Comprendre le versionning + fork   
( sauvegarder l'état d'un projet : "> git commit" + "> git push" )    
Revenir dans le temps à un état de sauvegarde passé   
( grace à son identifiant unique : hash/SHA )   
Auto-héberger une page sur GitLab    
( gratuit )    


## Éditer du code ...    
Le partager et envoyer les dernières modifications : 
GITLAB permet de travailler sans rien installer !    
Il embarque un IDE ( éditeur de code accessible en ligne )     
( IDE == Integrated Development Environment == Environnement de développement intégré )
On va travailler à partir de cet interface web       
mais on peut aussi l'installer "en local" :    




# UN APERCU des pouvoirs de Git : REVENIR DANS LE FUTUR

0. cloner un projet    

Depuis le terminal dans un dossier au choix     
> cd /chemin/vers/mon/dossier    
> git clone https://gitlab.com/bonnebulle/plain-html-redo.git     
> cd plain-html-redo    

( affichier le fichier index dans le navigateur pour voir )     
> firefox ./public/index.html
> chromium ./public/index.html

1. lister les comit précédents    
2. revenir à telle version du projet ( + **hash/SHA** )    

> git log --oneline
> git checkout 117647b

( affichier le fichier index dans le navigateur pour voir )     

3. revenir à la dernière version ( main )    
> git checkout main

( affichier le fichier index dans le navigateur pour voir )     


Une page en FRANCAIS qui résume les principales commandes GIT    
https://www.hostinger.fr/tutoriels/commandes-git   

( dont l'initialisation et configurat )    

! De façon générale, la documentation de Git est libre et en multi langues    
https://git-scm.com/docs

## GIT =?=  GitLab/Hub

### GIT versioning -- gestion de version, travail co

Git est un outil qui permet de créer et gérer des versions d'un projet    
On peut ainsi sauvegarder plusieurs fichiers modifiés d'un coup     
( en leur attribuant un identifiant unique + hash/SHA ... auquel se référer à l'avenir )    
Dans un developement à plusieurs, on peut, grâce à Git, avancer chacun sur une partie de l'écriture du projet    
et proposer par exemple des 'Branches' de dev. diférentes/divergentes, avancer sur une partie, tester...    
puis revenir en arrière si les modifications ne sont pas satisfaisantes ou posent problème ailleurs.

On peut ainsi avancer sur plusieurs fronts sans trop se géner quand on est à plusieurs sur un même code     
On peut aussi, pour les personnes exterieures au projet, observer les évolutions d'une version à l'autre    

Une certaine transparence qui peut aider à déceler du code malveillant ou à critiquer certains choix    
La maléabilité d'un projet ainsi sauvegardé en de multiples versions aide un  dev. souple et continu     
Si d'autres dev prennent une direction spécifique (branche) il sera ensuite possible de fusionner nos apports (merges)    
Et de régler alors d'éventuels conflits (si, par exemple nous avons travaillé sur la même portion de code)    

![roytuts](https://roytuts.com/wp-content/uploads/2021/11/image-70.png)     
( source : https://roytuts.com/git-branching-workflows-how-to-work-with-different-branches/ )


### Git Hub / Lab

Les dev pourraient s'envoyer les modifications directement entre elles (p2p) ...
mettre en place des flux d'actualité / newsletters/groups sur les derniers ajouts    
Mais le plus simple reste d'envoyer tout au même endroit : de centraliser sur un même serveur     
Git**Hub**/ou/**Lab** font ça :    
on leur envoit les dernieres modifications    
Des miliers de projets y sont hébergés (accessibles en ligne)    
La plateforme web Git**Hub**/ou/**Lab** mettent ainsi en relation des dev et public     
- On peut y **commenter** le code, 
- faire remonter un **problème** (issue) ( https://docs.github.com/fr/issues )    
- produire un historique des version (**changelog**)
- Ajouter des étoiles (stars/favoris) / financer    
: bref, faire avancé en commun un projet    
, par la mutualisation des besoins et des compétences    
- amander un code, proposer ses prorpres **branches** au projet    
etc.

C'est le côté "hub" / "lab", 2.0 de Git, sa mise en sociabilité web    
Git, sinon, c'est juste une modalité de sauvegarde des fichiers en local    
et des outils de comparaison d'une version à l'autre   
( on peut utiliser git en local, sans le web )

[GitHub](https://github.com) a été racheté par Microsoft    
Je préfère donc utiliser [GitLab](https://gitlab.com/)    
Voir les alternatives :    
https://alternativeto.net/software/gitlab/   



### PAGES auto-hébergées (distant / local)

L'un des intérets de GitLab/Hub c'est de facilement transformer un projet en site web gratuit et autohébergé !    
On pourra ensuit modifier une version locale de son site (sur son ordinateur)..    
et envoyer les modifications local vers github/lab (pour les rendre publiques) !

Local : mon ordi    
Distant : sur un serveur distant, par exemple l'un de ceux de Github/lab    
















# INSTALLER EN LOCAL :    


## Terminal -- commandes   
    
( utiliser la ligne de commande )    
https://openclassrooms.com/fr/courses/6173491-apprenez-a-utiliser-la-ligne-de-commande-dans-un-terminal/6349461-decouvrez-le-terminal#r-6349452    

! Tuto sympa (Anglais)    
https://coolguy.website/map-is-the-territory/introduction.html    


## Git :    
https://git-scm.com/downloads    

Vérifier via Terminal    
> git -v    


## Editeur (IDE)

( IDE == Integrated Development Environment == Environnement de développement intégré )
   
+ VSCODE / CODIUM :   
? https://alternativeto.net/software/codium/   
! https://github.com/Alex313031/codium/releases   
( WINDOWS : win32/64 .exe /ou/ MAC : x64/arm64 .dmg )   
! https://code.visualstudio.com/download    

passer en Francais :   
https://www.it-connect.fr/tuto-changer-langue-visual-studio-code-francais-anglais/

? Alt : JETBRAINS IDE   
https://www.jetbrains.com/webstorm/


---



# En ligne directement sur GitLab/Hub

CREER UN COMPTE GItLab/Hub    
https://gitlab.com/users/sign_up    


## TOKEN    

On aurra aussi besoin d'un Token d'accès....     
Un code long qui donne certaines autorisations ( par exemple pour pull/push/commit, etc )    

DO .... 
PAGE du PROJET -> GAUCHE    
-> Settings > Access Token    
--> Add New Token (boutton gris)   
--- Token name ...     
--- Select a role -> Owner   
--  Select scopes -->    
---- read_repository (pull)    
---- write_repository (push)    

Vérfier / Révoquer les acces :     
--> GOTO : https://gitlab.com/-/profile/preferences     


. . .     


# FORK PROJET (reprendre un projet existant)     

PROJET forké pour le cours :    
https://gitlab.com/bonnebulle/plain-html-redo

PAGE/PROJET d'origine :    
https://gitlab.com/pages/plain-html



DO ....     
GO https://gitlab.com/bonnebulle/plain-html-redo    

On clic "Fork"   
--> Cela va copier le projet existant dans tes projets sur les serveurs de GitLab/Hub    
--> Et tu pourras alors modifier cette version (copie) en toute libertée   

On précise la desintaion + nom du projet   
EX/ plain-html-redo_again    

. . .     

# METTRE EN LIGNE
Pour rendre le projet accessible en ligne, hébergé par GitLab/Hub...
"Transformer" en PAGE web :     

Dans le projet actuel ->
-> GAUCHE -> Build > Pipeline
-> New Pipeline (boutton bleu)    
-> Run Pipeline (boutton bleu)    
   
RESULTAT :    
PAGE URL ==    
- https://USERNAME.gitlab.io/PROJECT_NAME   
   
. . .     









# OUVRIR ou CLONER

### CHOIX - depuis gitLab/Hub : Edit avec l'IDE (le plus simple)

- DO ....     
RETOUR AU PROJET    
--> Edit ( à côté du boutton bleu )    
--> **Web IDE**   

( IDE == Integrated Development Environment == Environnement de développement intégré )

- Pour Ouvir 1 fichier spécifique... en ligne sur l'IDE embarquée de GitLab...     
/SI/ on veut travailler en ligne (IDE GitLab)...     
On peut ouvrir un fichier spécifique     
EX/ https://gitlab.com/bonnebulle/plain-html-redo/-/blob/main/README.md
--> Edit (boutton bleu)      
--> Open in Web IDE...    



### CHOIX - depuis le terminal (local)

On peut également cloner le projet depuis le terminal avec :    

> git clone https://gitlab.com/bonnebulle/plain-html-redo.git 




#### RAPPEL Terminal -- commandes   
    
( utiliser la ligne de commande )    
https://openclassrooms.com/fr/courses/6173491-apprenez-a-utiliser-la-ligne-de-commande-dans-un-terminal/6349461-decouvrez-le-terminal#r-6349452    

! Tuto sympa (Anglais)    
https://coolguy.website/map-is-the-territory/introduction.html    


#### détail - Terminal commandes (pwd/ls/cd)

/SI/ on veut le faire depuis Git/Labhub    
DO ....     
RETOUR AU PROJET    
--> Code (boutton bleu)    
--> Clone with HTTPS  (copy https.....monprojet.git)

Dans le terminal aller dans un dossier ou télécharger le projet     
. . .     
Chemin actuel     
> pwd   

Se déplacer cd     
EX dossier actuel/ ./(+press TABULATION)     
EX dossier parent/ ../(+press TABULATION)     
> cd ./
> cd ../

Une fois dans le bon dossier (au choix)     
> git clone https....monprojet.git    

lister fichiers clonés     
> ls    

--> dossier du projet    
--> on va dedans    
> cd monprojet
> ls   

Localiser le chemin du dossier actuel
> pwd






## PULL (aspirer == télécharger/sync/réccupérer dernière version)    

( à faire avant de modifier sa version locale du projet )    

Une fois un projet cloné.... quand on est dans son dossier on peut télécharger les dernières modifications apportées par les dev dans leur repertoire de travail git (distant)....    

Récupèrer les fichiers tels que présents sur GitLab/Hub    
( on récupère l'état de travail des fichiers présents sur le serveur )     
> git pull

( va prévenir si des modifications difèrent en local )     







# Git commandes depuis l'IDE local apres un clone

DEPUIS notre IDE, on va pouvoir sauvegarder l'état d'avancement du projet en utilisant GIT    
( qui se charge :    
- de cloner "> clone https://gitlab.com/bonnebulle/plain-html-redo.git"    
- de télécharger l'état actuel du projet présent sur le serveur git "> git pull"
- d'envoyer / sauvegarder "> git commit" + "> git push"
. . . )      

Les IDE ( tel VSCodium ) proposent d'envoyer ces commandes Git sans utiliser de terminal :    
via leur GUI ( Graphical User Interface )...    
en appuyant sur des bouttons visuels !    

- Ils donnent à voir l'état actuel du projet dans un Historique + Graph...    
Ils permettent...     
- d'ajouter les dernières modifications : "> git add *"
- de Commit ( sauvegarder avec un titre ) "> git commit" ...
... en toute simplicité !    
... mais pour apprendre il est bien de se familiariser avec les lignes de commande...   
... de passer du temps via le terminal !   
... ainsi on comprend ce qui se passe "derière" quand on clic les boutons     
... ( quelles commandes sont envoyées )    


TUTO VSCODE :    
https://code.visualstudio.com/docs/sourcecontrol/intro-to-git    

![](https://bulle.vincent-bonnefille.fr/pj/git_cours/vscode_git.png)




## TUTOS + COMMANDES (terminal)

- Git - Git dans Bash     
↳ https://git-scm.com/book/fr/v2/Annexe-A:-Git-dans-d%e2%80%99autres-environnements-Git-dans-Bash     
     
- Git - Git dans IntelliJ / PyCharm / WebStorm / PhpStorm / RubyMine     
↳ https://git-scm.com/book/fr/v2/Annexe-A:-Git-dans-d%e2%80%99autres-environnements-Git-dans-IntelliJ-/-PyCharm-/-WebStorm-/     -PhpStorm-/-RubyMine
     
- Git - Git dans Visual Studio Code     
↳ https://git-scm.com/book/fr/v2/Annexe-A:-Git-dans-d%e2%80%99autres-environnements-Git-dans-Visual-Studio-Code     







## Etat des fichiers + processus intermédiaires

- staged/stash - état intermédaire des fichiers priss en compte (ou pas)       
- puis commit - sauvegarde de cet état de cet état (staged) du projet,    
- puis envoi - push    

![](https://bulle.vincent-bonnefille.fr/pj/git_cours/git_workflow_002-3557173400.png)      
( source : https://nulab.com/learn/software-development/git-tutorial/git-basics/ )      

![](https://bulle.vincent-bonnefille.fr/pj/git_cours/explained-git-basic-workflow.png)      
( source : https://tecadmin.net/basic-git-workflow/ )    

![](https://bulle.vincent-bonnefille.fr/pj/git_cours/git-add-commit-144050348.png)      
( source : https://www.earthdatascience.org/workshops/intro-version-control-git/basic-git-commands/ )    



Quand un fichier est modifié, pour enregistrer son état actuel, ici, en local..    
... dans un état actuel : **staged**       
--> **staged** == "stade" / "état"   

... la version prise en compte se retrouve dans un espace disque de sauvegarde "**satsh**"    
... les fichiers dans le **stash** (et leur état **staged**) sera pris en compte durant le prochain **commit**    
.... le **commit** permet d'indiquer aux autres utilisateurs quelles modifications ont été apportées au projet    
.... Je peux indiquer ce qui marche et expliquer les modifications     
.... la dernière étape sera d'envoyer l'état actuel des fichers (**staged/stash**) et le commentaire du **commit** ... au serveur !   
... ! Pour l'user : D'autres utilisateur.ices pourrons ainsi se référer à ce point de sauvegarde    
..... ( par son nom et son identifiant unique **hash/SHA** )    
..... restaurer ou étudier le code depuis ce point de sauvegarde     
... ! Pour la/le dev : **plutôt que d'envoyer un à un chaque fichier, cette méthode permet de tout synchroniser d'un coup**    
.... quand le commit est prêt on `git push` !


## Etat des fichiers -- staged/stash - status 

On peut voir l'état des fichiers :    
> git status

EX/
```bash
Sur la branche main
Votre branche est à jour avec 'origin/main'.

Modifications qui seront validées :
  (utilisez "git restore --staged <fichier>..." pour désindexer)
	nouveau fichier : NEW_file_ready.md

Modifications qui ne seront pas validées :
  (utilisez "git add/rm <fichier>..." pour mettre à jour ce qui sera validé)
  (utilisez "git restore <fichier>..." pour annuler les modifications dans le répertoire de travail)
	supprimé :        fullyfly.md

Fichiers non suivis:
  (utilisez "git add <fichier>..." pour inclure dans ce qui sera validé)
	NEW_file.md
```

- "non suivis" == le fichier n'a pas été ajouté (add) en **staged**         
- "qui ne seront pas validées" == fichier supprimé dans les fichiers (mais pas avec git rm)    
- "qui seront validées" == sont dans le stash (ajoutés)    


On nous indique alors ceux qui sont modifiés, les quels sont dans le **staged** (ou non)    
.. quels fichiers seront compris dans le prochain **commit** (et comment)    

### ADD

On peu ensuite ajouter l'état actuel de nos fichiers (modifications) au **staged**    
Ajouter un fichier (ou tous *)
> git add ./README.md
> git add *

### RM / checkout / restore

Remove du staged (état lattant avant commit + push)    
... Cela ne supprime pas le fichier sur notre ordinateur/serveur (en local)    
... mais cela le retire du staged, de la liste des fichiers qui seront affectés par le prochain commit    
> git rm ./README.md

annuler un ajout sur un fichier    
> git checkout -- CONTRIBUTING.md

restaure     
> git restore --staged CONTRIBUTING.md



## Commit + éditeur

( sauvegarder l'état actuel des fichiers locaux )   
( tel que pris en compte dans le **staged** )     
> git commit    

### Editeur - ligne de commande

/CHOIX/ on peut écrir les modifications directement depuis la commmande      

> git commit -m 'initial commit of my project'   

### Editeur - nano / vim / autres

/CHOIX/ on écrit les modifications apportées dans l'éditeur de text dans le shell/terminal   

. on peut installer nano https://command-not-found.com/nano    
   
. ou utiliser Vim ( un autre éditeur )...    
... ( les commandes se font au clavier )
... ( : indique une commande )
... --> https://vim.rtorr.com    
....    
.... on tappe -- ESCAPE + ":a" pour rendrer en mod édition   
.... on quitte+save en tappant -- ESCAPE + ":wq"    
.... on quitte no_save tappant -- ESCAPE + ":q!"    

. ou autre éditeur tel VSCodium    

### Editeur - définir par défaut

/DO/    
> git config --global core.editor nano
( détail : https://git-scm.com/book/fr/v2/Démarrage-rapide-Paramétrage-à-la-première-utilisation-de-Git )    






## Log
Visualiser les modifications :     
> git log -p -2
> git log --pretty=oneline

## History
voir l'historique    
> git log --pretty=format:"%h %s" --graph

## Sur GitLab/Hub
On peut retrouver les commit ici ;
> EX/ https://gitlab.com/USER_NAME/PROJECT_NAME/-/commits/main?ref_type=heads









# ENVOYER

## PUSH

Envoi des modifications après un commit    
( qui valides les modifications locales apportées à tel ou tel fichier )    
> git push
( id + TOKEN )    

préciser la branch à qui envoyer le commit (et fichiers)     
> git push --set-upstream origin main
( id + TOKEN )    





# RESET / CHECKOUT (retour vers le passé/futur)

_RESET réinitialise l'état du projet par son **hash/SHA**_
_CHECKOUT est moins permanent, il permet de retrouver l'état d'un projet sans réinitialiser l'état des fichiers modifiés_   

à chaque commit un identifiant unique est créé (hash/SHA)    
> EX/ 27162d625d6665a824be74c281d07f6894f16888

On peut retrouver les commit ici ;
> EX/ https://gitlab.com/USER_NAME/PROJECT_NAME/-/commits/main?ref_type=heads

En faisant un reset hard on retrouve les fichiers telque durant le dit commit    
> git reset --hard 27162d625d6665a824be74c281d07f6894f16888



## RAPPEL Git : REVENIR DANS LE FUTUR

**CHECKOUT permet de revenir à l'état d'un commit passé SANS RESET (réinitialiser) les fichiers locaux**
_CHECKOUT marche pour les retour vers une version passée/futur : un commit (hash/SHA) /OU/ BRANCHE_

0. cloner un projet    

Depuis le terminal dans un dossier au choix     
> cd /chemin/vers/mon/dossier    
> git clone https://gitlab.com/bonnebulle/plain-html-redo.git     
> cd plain-html-redo    

( affichier le fichier index dans le navigateur pour voir )     
> firefox ./public/index.html
> chromium ./public/index.html

1. lister les comit précédents    
2. revenir à telle version du projet ( + **hash/SHA** )    

> git log --oneline
> git checkout 117647b

( affichier le fichier index dans le navigateur pour voir )     

3. revenir à la dernière version ( main )    
> git checkout main

( affichier le fichier index dans le navigateur pour voir )     




# BRANCHES   

TUTO : https://git-scm.com/book/fr/v2/Les-branches-avec-Git-Les-branches-en-bref     

voir les branches ( locales + distantes )    
> git branch --all


CHECKOUT    
Changer de branche    

TUTO https://git-scm.com/book/fr/v2/Les-branches-avec-Git-Gestion-des-branches     

changer (basculer de branche)    
> git checkout -b forkit

revenir/changer à la branche d'origine "main" (ou "forkit")  
> git checkout main
> git checkout forkit

envoyer les modifications à une branche spécifique    
> git push --set-upstream origin main

# Merge    
> git merge forkit

gestion de conflit de versions     
TUTO :     
- https://git-scm.com/book/fr/v2/Les-branches-avec-Git-Branches-et-fusions%C2%A0:-les-bases#s_basic_merging
> git status
> git mergetool






---

# READ_ME D'origine :

Example plain HTML site using GitLab Pages.

Learn more about GitLab Pages at https://pages.gitlab.io and the official
documentation https://docs.gitlab.com/ce/user/project/pages/.

---

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [GitLab CI](#gitlab-ci)
- [GitLab User or Group Pages](#gitlab-user-or-group-pages)
- [Did you fork this project?](#did-you-fork-this-project)
- [Troubleshooting](#troubleshooting)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## GitLab CI

This project's static Pages are built by [GitLab CI][ci], following the steps
defined in [`.gitlab-ci.yml`](.gitlab-ci.yml):

```yml
image: busybox

pages:
  stage: deploy
  script:
  - echo 'Nothing to do...'
  artifacts:
    paths:
    - public
    expire_in: 1 day
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
```

The above example expects to put all your HTML files in the `public/` directory.

## GitLab User or Group Pages

To use this project as your user/group website, you will need one additional
step: just rename your project to `namespace.gitlab.io`, where `namespace` is
your `username` or `groupname`. This can be done by navigating to your
project's **Settings**.

Read more about [user/group Pages][userpages] and [project Pages][projpages].

## Did you fork this project?

If you forked this project for your own use, please go to your project's
**Settings** and remove the forking relationship, which won't be necessary
unless you want to contribute back to the upstream project.

## Troubleshooting

1. CSS is missing! That means that you have wrongly set up the CSS URL in your
   HTML files. Have a look at the [index.html] for an example.

[ci]: https://about.gitlab.com/solutions/continuous-integration/
[index.html]: https://gitlab.com/pages/plain-html/-/blob/main/public/index.html
[userpages]: https://docs.gitlab.com/ee/user/project/pages/introduction.html#gitlab-pages-in-projects-and-groups
[projpages]: https://docs.gitlab.com/ee/user/project/pages/introduction.html#gitlab-pages-in-projects-and-groups