diff --git a/README.md b/README.md index 6eaee07a2422ba546c2d56e78d2332ef636a2aea..9755636b23b6ad21371332627140a1afc64ca5bf 100644 --- a/README.md +++ b/README.md @@ -1,395 +1,3 @@ -[Hier gehts zum WIKI](https://git-ce.rwth-aachen.de/assistance-systems/helloworld/-/wikis/home) - -Dieser Wiki Artikel soll dir den allgemeinen Umgang mit git als Dateiablage mit Versionsverwaltung vermitteln. Zum Einstieg empfiehlt es sich die die Kapitel nacheinander und mit eigenem Rechner auszuprobieren. - -[[_TOC_]] - -# **Rollen in einem Git-Repository** -<details> -<summary>Die 5 Rollen in einem Respository</summary> - -* **Owner** - Besitzer der Repository. Er besitzt alle Rechte und hat keine Einschränkungen in der Verwaltung eines Repositories. -* **Maintainer** - Pflegt die Repository und kann die Rollenverteilung der Mitglieder verwalten. -* **Developer** - Kann Programmcode in das Repository hinzufügen (Push). -* **Reporter** - Kann das Repository durchforsten und vorhandene Issues an die Developer verteilen. -* **Guest** - Hat die wenigsten rechte. Als Gast kann man lediglich sich das Repository anschauen und klonen - -Eine genauere Auflistung aller Rechte ist unter folgendem Link zu finden: -`https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions` - -</details> - - -# **Begriffserklärung** -<details> -<summary>Wichtige Begriffe</summary> - -* **Repository** - Ist ein verwaltetes Verzeichnis zur Speicherung und Beschreibung digitaler Objekte für ein digitales Archiv (Projekt). -* **Branch** - Entwicklungszweig eines Projektes, wichtig für die gleichzeitige Entwicklung eines Projektes. Wird ein Branch zum Hauptzweig des Repositories zurück geführt so wird dies als Merge bezeichnet. -* **Index** - Auflistung der aktuell bereitgestellten veränderten Dateien. -* **Snapshot** - Abbild der aktuell bereitgestellten Änderungen - -**Git-Befehle** -* **Clone** - Legt eine lokale kopie eines existierenden Git-Repository an. -* **Pull** - Wird verwendet, um Inhalte aus einem Remote-Repository herunterzuladen und das lokale Repository zu aktualisieren. -* **Add** - Fügt die veränderten Dateien zum sogenannten Index hinzu. -* **Commit** - Erfasst einen Snapshot (Abbild) der aktuell bereitgestellten Änderungen, die Dateien im Index, des Projekts. -* **Push** - Lädt Inhalte aus dem Snapshot in ein Remote-Repository hoch. - - - - - -</details> - - -# **Passwort für den HTTPS Zugriff erstellen** -<details> -<summary>Passwort</summary> - -**a)** In Gitlab _Personal Profile_ (oben rechts) -> _Edit Profile_ auswählen und in der linken Leiste auf _Password_ klicken - - - -**b)** Passwort einstellen - -Im _Password_ Tab ein Passwort eingeben **(1)** (einfachheitshalber das Passwort für die CampusID eingeben) und _Save Password_ klicken **(2)**. Nach erfolgtem Passwort wechsel wird man ausgeloggt und muss sich mit dem neuen Passwort einloggen. - - - -</details> - - -# **Ermitteln des eigenen Benutzernamens** -<details> -<summary>Benutzername</summary> - -In Gitlab _Personal Profile_ (oben rechts) findet man den eigenen Benutzernamen. Der Benutzername wird später benötigt und sollte nicht geändert werden. - - - -</details> - -# **Finden der Repository-Adresse** -<details> -<summary>Kopieren der Repository-Adresse</summary> - -Die Repository-Adresse kann auf der Repository Seite eingesehen und in die Zwischenablage kopiert werden. Dafür klickt man auf _Clone_ **(1)** und kopiert den https link **(2)**. Diese lautet in diesem Fall `https://git-ce.rwth-aachen.de/assistance-systems/helloworld.git` - - - -</details> - -# **Installation von Git** -<details> -<summary>Installation von Git.</summary> - -**MacOS:** -Suche und öffne das Terminal in der Programmübersicht oder die Suchleiste (cmd+Leertaste). Anschließend führe folgenden Befehl aus: - -`git` - -Es öffnet sich ein Pop-Up-Fenster, welches eine Abfrage nach der Installation der Command Line Developer Tools fragt. Bestätige diese über Installieren. - - - -**Ubuntu:** Um Git auf Ubuntu zu installieren öffnet man das Terminal (STRG+ALT+T) und führt folgende Befehle aus: - -`sudo update` - -`sudo apt install git` - - -**Windows:** Um Git auf Windows zu installieren downloadet man die Installationsdatei von `https://gitforwindows.org/` und führt diese aus. Während der Installation sollten alle Voreinstellungen von git beibehalten werden. - -## _Vorbereitung (Einmalig nach Installation)_ - -Für _user.name_ sollte man den zuvor ermittelten Benutzernamen und für _user.email_ die TH-Köln E-Mail Adresse wählen. - -**Terminaleingabe (MAC/WINDOWS/LINUX):** - -`git config --global http.sslVerify false` - -`git config --global user.email "max.mustermann@smail.th-koeln.de"` - -`git config --global user.name "mmustermann"` - -Beispiel: - - -**Zusätzlich für WINDOWS:** - -Um das Git-Terminal zu starten klickt man mit der rechten Maustaste auf eine freie Stelle in einem Ordner und wählt _Git Bash Here_ aus. - -## _Hinzufügen eines SSH Keys (optional)_ - -Die Authentifizierung beim GitLab Server kann entweder mit Username und Passwort oder mit Hilfe eines SSH Keys durchgeführt werden. Möchte man die Authentifizierung mit einem SSH KEY durchführen, so muss zuerst ein Schlüsselpaar bestehend aus einem privaten und einem öffentlichen Schlüssel erzeugt werden. Im Folgenden wird dafür der Verschlüsselungsalgorithmus EdDSA verwendet. Alternativ kann auch RSA verwendet werden. - - -**Terminaleingabe (MAC/WINDOWS/LINUX):** - -`ssh-keygen -t ed25519 -C "<Kommentar>"` - -Anschließend erscheint der folgende Output: - -``` -Generating public/private ed25519 key pair. -Enter file in which to save the key (/home/<user>/.ssh/id_ed25519): -``` - -Hier kann nun ein Speicherort für die Schlüssel angegeben werden. Durch Drücken der `Enter`-Taste ohne eine Eingabe wird der vorgeschlagene Speicherort verwendet. - -Anschließend kommt noch die Frage, ob man ein Passwort (passphrase) für den privaten Schlüssel anlegen möchte. - -``` -Enter passphrase (empty for no passphrase): -Enter same passphrase again: -``` - - -Dies dient dazu, dass der Schlüssel selbst noch einmal mit einem Passwort geschützt ist, sodass der alleinige Besitz der Datei nicht zur Authentifizierung ausreicht. Mit einem Passwort handelt es sich dann um eine 2-Faktor-Authentifizierung. - -Anschließend muss der öffentliche Schlüssel bei GitLab hinterlegt werden. Hierzu muss der Inhalt der Datei des öffentlichen Schlüssels kopiert und bei GitLab hinzugefügt werden. - - -**macOS:** -```tr -d '\n' < ~/.ssh/id_ed25519.pub | pbcopy``` - -**Linux** (benötigt `xclip` Paket): -```xclip -sel clip < ~/.ssh/id_ed25519.pub``` - -**Git Bash bei Windows:** -```cat ~/.ssh/id_ed25519.pub | clip``` - -Nach der Ausführen des entsprechenden Befehls befindet sich der öffentliche Schlüssel in der Zwischenablage. - -Nun muss man sich bei GitLab einloggen und oben rechts auf den Avatar klicken. Anschließend klickt man auf **Preferences**. Dann klickt man auf der linken Leiste auf **SSH Keys**. In die **Key** Box kopiert man nun den Inhalt aus der Zwischenablage (`Strg` + `V`) und drückt anschließend auf **Add key**. - - - -</details> - -# **Benutzen von Terminalbefehlen** - - -## Pfadeinstellungen -<details> -<summary>Pfadeinstellungen</summary> - - - -Die folgenden Befehle können nur ausgeführt werden, wenn der angezeigte Pfad im Terminal das Hauptverzeichnis des lokalen Repositories ist. Um im Terminal den Pfad zu wechseln gibt man folgenden Befehl ein, wobei <Pfad> der Zielpfad ist, zu dem man wechseln möchte: - -`cd <Pfad>` - -Für den Befehl `Clone` ist das ein beliebiger Ordner auf dem PC. -Für die restlichen Befehle ist das anschließend der Ordner mit dem Namen des **remote-repositories**, der beim Klonen erstellt wurde. - -**Beispiel:** -So kann das bspw. ein Ordner auf dem Desktop sein, in dem das geklonte Projekt gespeichert wird: - -`/Users/<users>/Desktop/Local_repository` - -Nach dem Klonen wird dann mit - -`cd helloworld` - -in den Ordner gewechselt, in dem auch ein untergeordneter **branch** erstellt werden kann. -</details> - - - -## Klonen der Repository (Projekt) -<details> -<summary>Klonen.</summary> +# Bitte das WIKI zu diesem Repository lesen -Um ein Projekt zu Klonen, erstellt man ein Neuen Ordner für das Projekt, startet das Git-Terminal und wechselt in den Pfad des eben erstellten Ordners. - -Dann wird folgender Befehl im Terminal eingegeben: - -`git clone <Repository-Adresse>` - -In unserem Fall lautet die Repository-Adresse: - -`https://git-ce.rwth-aachen.de/assistance-systems/helloworld.git` - -Der Befehl zum Klonen von diesem Repository lautet demnach: - -`git clone https://git-ce.rwth-aachen.de/assistance-systems/helloworld.git` - -Nach erfolgreicher Eingabe von Benutzernamen und Passwort wird das Repository geklont. -</details> - - - -## Erstellen von einem Branch -<details> -<summary>Branch erstellen</summary> - - -Um den neuen lokalen Branch (hier: Test) zu erstellen und in diesen Branch zu wechseln, gibt man folgenden Befehl ein: - -`git checkout -b Test` - -> Mit dem checkout-Befehl ist es möglich jederzeit zwischen den verschiedenen Branches zu wechseln. - -Nun wird mit dem push-Befehl der Branch _Test_ zum GitLab-Projekt (auf dem Server) hinzugefügt: - -`git push origin Test` - -</details> - - - -## Pushen von Daten -<details> -<summary>Pushen</summary> - -**a)** Wenn Änderungen im lokalen Repository vorgenommen wurden, dann sollten diese zum Index mit folgendem Befehl hinzugefügt werden: - -`git add .` - -**b)** Nun kann ein Commit einschließlich einer Kurzbeschreibung der Änderung mit folgendem Befehl durchgeführt werden: - -`git commit -m "Hier steht ein Kommentar"` - -> Dadurch wird nicht das Repository auf GitLab aktualisiert, sondern nur das lokale Repository. - -**c)** Nun können die Änderungen mit folgendem Befehl zum Remote-Repository hinzugefügt werden: - -`git push <REMOTE> <BRANCHNAME>` - -> <REMOTE> ist der Name des remote Servers. Wenn ein Projekt geklont wird, dann ist der von git vergebene Standardname `origin`. - -In unserem Beispiel lautet der Befehl somit: - -`git push origin Test` - - -</details> - - -## Pullen von Daten -<details> -<summary>Pullen</summary> - -Um Änderungen an einem remote Repository zu downloaden und mit dem lokalen Repository zu synchronisieren wird folgender Befehl ausgeführt: - -`git pull <PFAD> <BRANCHNAME>` - -> **Pfad** ist die Repository-Adresse. In unserem Beispiel lautet diese: `https://git-ce.rwth-aachen.de/assistance-systems/helloworld.git` - -Für unser Beispiel lautet der Befehl somit: - -`git pull https://git-ce.rwth-aachen.de/assistance-systems/helloworld.git Test` - - -</details> - - -# **Alternative: GUI** -<details> -<summary>Installation & Benutzung einer GUI.</summary> - -<details> -<summary>Installation von git-cola auf deinem Rechner</summary> - -Für die installation der GUI _git-cola_ befolgt man die Anleitung für das jeweilige Betriebssystem auf folgender Seite: -`http://git-cola.github.io/downloads.html` -</details> - -<details> -<summary>Klonen des Projekts (Repository)</summary> - -Ziel ist das Klonen des Repositories "HelloWorld" auf das eigene System, um lokal auf die Inhalte zugreifen zu können. Mithilfe von git-cola erfolgt dies auf allen Systeme analog. Einzig das SSL-Zertifikat und die Benutzerdaten müssen zuvor **einmalig** hinterlegt werden. - -**a)** Starte _git-cola_ und klicke auf _Klonen..._ - - - -**b)** Job-Spezifikation -Anschließend erfolgt die Eingabe der Repository-Adresse und auswahl des Speicherpfades. - - - -**c)** Es wird nach einer Authentifizierung gefragt. Hierzu den zuvor ermittelten Benutzernamen und das festgelegte Passwort eingeben. -> ID: mmustermann -> PW: 123456 - -**d)** Nun wurde das Projekt geklont und es muss ein neuer Branch erstellt werden. -</details> - - -<details> -<summary>Erstellen von einem Branch</summary> - -Zum erstellen von einem neuen Branch klickt man auf _Branch_ **(1)** und anschließend auf _Neu_ **(2)** - - - -Anschließend gibt man dem neuen Branch einen Namen, z.b. Gruppe01 **(1)** und klickt auf _Branch erstellen_ **(2)**. - - -</details> - - -<details> -<summary>Pushen des Projekts</summary> - -Die lokal vorhandenen Branches werden unter _Branches_ **(1)** angezeigt, wo der aktuell ausgewählte Branch mit einem Stern gekennzeichnet ist. - -Geänderte bzw. hinzugefügte Daten im geklonten Projekt Ordner werden im Hauptfesnter unter Zustand **(2)** angezeigt. Durch Doppeltklick auf die geänderten bzw. hinzugefügten Daten merkt diese für den Upload (Push) vor. Dies wird durch einen grünes Dreieck gekennzeichnet. - -Um Daten uploaden (pushen) zu können, muss unter _Commit_ **(3)** einen kommentar eingeben werden (ggf. kann auch eine ausführliche Beschreibung hinzugefügt werden). Anschließend klickt man auf _Commit aufnehmen_. Dabei verschwinden die Daten aus dem Bereich Zustand **(2)**, was aber kein Grund zur sorge ist. - - - - - -Zum hochladen der Daten klickt man auf _Befehle_ **(1)** und anschließend auf _Veröffentlichen_ **(2)**. - - - -Anschließend klickt man im nächsten Fenster auf _Veröffentlichen_, wenn man noch keinen Branch veröffentlicht hat. Daraufhin erscheint eine Meldung, dass der Branch noch nicht existiert und ob dieser erstellt werden soll, dies bestätigt man mit klick auf _Externen Branch erstellen_. - - - - - -Sollte schon ein externer Branch erstellt worden sein, so wählt man diesen zuvor aus **(1)** und klickt auf _Veröffentlichen_ **(2)**. - - -</details> - - -<details> -<summary>Pullen eines Projektes</summary> - -Sollte das git-Repo (Projekt) unterschiede zur lokalen Kopie aufweisen, muss vor dem arbeiten am Projekt ein sog. "pull" stattfinden. - -Dafür wählt man den Reiter _Befehle_ **(1)** aus und klickt auf _Holen und zusammenführen_ **(2)**. - - - -Anschließend wählt man den Branch aus von dem man den sog. Pull machen möchte **(1)** und klickt auf _Holen und zusammenführen_ **(2)**. - - -</details> - -</details> - - - - -# **Weiterführende Themen:** -## Lokales Projekt in GitLab anlegen -* [Workflow: lokales Projekt in GitLab anlegen](https://git-ce.rwth-aachen.de/assistance-systems/helloworld/-/wikis/Workflow:-lokales-Projekt-in-GitLab-anlegen) - -## Integration der Git Funktionen im Finder (Mac!) -* [Integration der Git Funktionen im Finder (Mac!)](https://git-ce.rwth-aachen.de/assistance-systems/helloworld/-/wikis/Integration-der-Git-Funktionen-im-Finder-(Mac!)) - -## Readme für Projekt und Abschlussarbeiten -* [Readme für Projekt und Abschlussarbeiten](https://git-ce.rwth-aachen.de/assistance-systems/helloworld/-/wikis/Anlegen-des-Wikis-f%C3%BCr-Projekt-und-Abschlussarbeiten) - -## Quelltext konventionen -* [Quelltext konventionen](https://git-ce.rwth-aachen.de/assistance-systems/tools/helloworld/-/wikis/Quelltext-konventionen) +[Hier gehts zum WIKI](https://git-ce.rwth-aachen.de/assistance-systems/helloworld/-/wikis/home)