Informatik/Mathematik / Software Engineering

Ziel: Einrichtung und Kennenlernen der Grundlagen zur Nutzung von GitHub, Git, Visual Studio Code als Editor/Arbeitsumgebung und das Anlegen eines ersten Dokumentes mit AsciiDoc-Syntax

Praktikumsaufgaben Teil 1 - Grundlagen

Vorbereitung privater Rechner

Bearbeiten Sie die Aufgaben an Ihrem privaten Rechner, müssen Sie, falls noch nicht vorhanden, Git, Asciidoctor und Visual Studio Code installieren.

Die zusammengefassten Hinweise zu der Installation für Windows, Linux und macOS finden Sie unter Installation & Konfiguration.

1. GitHub

Aufgabe 1.1 - Login

  1. Loggen Sie sich auf der Webseite github.com ein. Sollten Sie noch keinen Account haben, kann er über https://github.com/join erstellt werden.

    Sie haben die Wahl, ob Sie einen neuen Account für ihre HTW-E-Mail-Adresse erstellen oder sie ihrem bestehenden Account ihre HTW-E-Mail-Adresse über Settings  Emails hinzufügen.

Ist dem GitHub-Account die HTW-E-Mail-Adresse hinzugefügt oder dieser direkt damit angelegt worden, können über das GitHub Education Programm weitere Features von GitHub freigeschaltet und an weiteren Bonusprogrammen teilgenommen werden.

Aufgabe 1.2 - Repository Anlegen

  1. Erstellen Sie ein privates Repository mit folgenden Einstellungen:

    • Repository name: htwd-se-example-project

    • Description: Beispielprojekt für die Praktikumsaufgaben zum Thema Git und AsciiDoc

    • Initialize this repository with a README: Ja

Aufgabe 1.3 - Repository Ändern

  1. Bearbeiten Sie die Datei README.md direkt auf GitHub und ersetzen Sie den Inhalt mit der unten angegebenen Vorgabe. Nehmen Sie die Änderung über Commit changes als neue Version in das Repository auf.

    Ist die Datei README.md nicht vorhanden, legen Sie eine neue Datei README.md über Create new file in Ihrem Repository auf GitHub für die Projekt-Beschreibung im Markdown-Format an.

    README.md
    # SE Praktikum - Beispielprojekt

Ein Beispielprojekt für die Praktikumsaufgaben zum Thema Git und
AsciiDoc im Fach Software Engineering I.

## Praktikumsinhalt

- Umgang mit **Git**, **AsciiDoc** und **GitHub**

(Aufgabe 1.4 - Access Token anlegen)

Als Alternative zum Login mit dem GitHub Account, kann auch ein Personal Access Token verwendet werden. Mit den Tokens (Personal access tokens) können, ähnlich wie bei GitHub OAuth, Anwendungen gezielt eingeschränkte Zugriffsmöglichkeiten gegeben oder entzogen werden, ohne das Accountpasswort preiszugeben.

Hinweise zum Anlegen einen Personal Access Token (Classic)

Anleitung für das Anlegen von Access Token: Creating a personal access token

  1. Legen Sie auf GitHub über Settings  Developer settings  Personal access tokens einen neuen Token bspw. Praktikum SE I mit einer Gültigkeit für dieses Semester und nur dem Scope repo und workflow an.

    Der Personal access token ist nur nach dem Erstellen zu sehen und kann danach nicht wieder angezeigt werden!

    In den Laboren (Windows) werden ihre Profile nicht gespeichert, was zum Verlust des verwendeten Passwortes/Tokens nach dem Abmelden führt, weswegen wir zu jedem Praktikum wiederholt diesen Token für die (erste) Kommunikation mit Git zu GitHub benötigen.

    • Möglichkeit 1: Sie speichern den generierten Token an geeigneter Stelle ab, um diesen in jedem Praktikum wiederholt verwenden zu können.

    • Möglichkeit 2: Sie lassen sich zu jedem Praktikumsbeginn den vorhandenen Token über Regenerate token neu generieren.

Seit dem 13. August 2021 akzeptiert GitHub für die Authentifizierung von Git-Operationen über HTTPS nur noch GitHub OAuth oder Personal access tokens statt des Account Passwortes. (Quelle)

Hinweise: Fehlermeldung
Eine Verwendung des Passwortes über HTTPS führt zu folgendem Fehler:
remote: Support for password authentication was removed on August 13, 2021. Please use a personal access token instead.
remote: Please see https://github.blog/2020-12-15-token-authentication-requirements-for-git-operations/ for more information.

2. Git

Aufgabe 2.1 - Konfiguration

Für die Verwendung von Git müssen Sie Ihren Name, Ihre E-Mail und eventuell einen Proxy festlegen.

Die angegebene E-Mail dient zur Identifizierung ihrer Änderungen am Repository und zur Zuordnung ihres GitHub Accounts. Der Proxy ist notwendig, damit Sie aus dem geschützten HTW-Netz (Labore, VPN, WLAN) sich mit dem Internet verbinden können.

Die globale Konfiguration von Git wird auf Ihrem Rechner im Benutzerverzeichnis, siehe Tabelle 1, “Speicherort der globalen Git-Konfiguration”, in der Datei .gitconfig abgelegt. Sie gilt global für alle Ihre Git-Repositories.

Tabelle 1. Speicherort der globalen Git-Konfiguration

Linux

~/.gitconfig

macOS

~/.gitconfig

Windows

C:\Users\<username>\.gitconfig

Arbeiten Sie auf Ihrem (privaten) Rechner mit verschiedenen Git-Identitäten (andere E-Mail für Privat, Studium, Arbeit, …​), können Sie auch spezifische Konfigurationen je Repository verwenden.

  1. Nur für privaten Rechner notwendig: Starten Sie Visual Studio Code und öffnen Sie über Ctrl+Shift+G (View  SCM) den Bereich des Source Controle Managements, welcher für die Versionsverwaltung zuständig ist. Taucht hier ein Meldung ähnlich wie: "A valid git installation was not detected …​ Please install git …​" auf, schauen sie bitte unter Vorbereitung privater Rechner nach, ob sie Git installiert haben.

  2. Öffnen Sie Ihren Dateimanager und schauen Sie nach, ob es schon eine .gitconfig Datei gibt (Siehe Tabelle 1, “Speicherort der globalen Git-Konfiguration”).

  3. Öffnen Sie in Visual Studio Code über File  Open…​ die schon vorhandene Datei .gitconfig oder legen Sie eine neue Datei über File  New File an. Passen Sie den Inhalt wie folgt an:

    Inhalt der .gitconfig - HTW Laborrechner
    [user]
	name = Vorname Nachname
	email = s00000@htw-dresden.de
[safe]
  directory = * (1)
[http]
	proxy = http://www-cache.htw-dresden.de:3128
    1 Erlaubt es Git, Repositories auf (Netz-)Laufwerken mit unterschiedlichen Eigentümer-Einstellungen trotz fatal: unsafe repository-Sicherheitsmeldung zu nutzen.
    Dies in den Windows-Laboren der HTW der Fall, wenn sie auf ihrem Studenten-Laufwerk (U:) arbeiten.
    Hinweise: Git-Meldung: fatal: unsafe repository

    Git verweigert, seit Version 2.35.2, aus Sicherheitsgründen (Security Fix CVE-2022-24765) die Nutzung von Repositories auf (Netz-)Laufwerken mit unterschiedlichen Eigentümer-Einstellungen. Möchte man diese trotzdem nutzen, muss dies über die Konfiguration (Einstellung: safe.directory) von Git explizit erlaubt werden.

    Für alle betreffenden Repositories erlauben:

    Mit git config --global --add safe.directory * oder direkt über die .gitconfig muss folgendes hinzugefügt werden:

    [safe]
  directory = * (1)
    1 Der *-Stern dient als Platzhalter für alle betreffenden Repositories, egal in welchem Verzeichnispfad sie sich befinden.
    Nur ein bestimmtes Repository erlauben:

    1. Terminal öffnen, bspw. in VS Code: View  Terminal

    2. zum passenden Repository-Verzeichnis navigieren cd path/to/repo

    3. im Terminal git status ausführen

      fatal: unsafe repository ('//141.56...)
To add an exception for this directory, call:

        git config --global --add safe.directory '%(prefix)///141.56...

    4. Befehl git config --global --add safe.directory…​ aus obiger Meldung ausführen

    5. im Terminal git status noch einmal ausführen

    Inhalt der .gitconfig - privater Rechner
    [user]
	name = Vorname Nachname
	email = s00000@htw-dresden.de

    Für die E-Mail verwenden Sie bitte eine ihrer HTW Adressen mit s00000@informatik.htw-dresden.de, s00000@htw-dresden.de oder vorname.nachname@htw-dresden.de, welche in Ihrem GitHub-Account verwendet wird.

  4. Speichern Sie die gemachten Änderungen über File  Save bzw. strg+s oder cmd+s.

    Ist die Datei neu: Speichern Sie die neue Datei über File  Save As…​ und wählen Sie als Datei-Typ/Format: All files aus. Geben Sie jetzt den Dateinamen .gitconfig an und speichern Sie in Ihrem Benutzerverzeichnis (Siehe Tabelle 1, “Speicherort der globalen Git-Konfiguration”).

  5. Zum Testen der Konfiguration öffnen Sie in Visual Studio Code über Ctrl+Shift+´ (View  Terminal) das integrierte Terminal oder ein beliebiges anderes Terminal (Windows: PowerShell) und geben folgende Git-Kommandos ein:

    Anzeige des festgelegten Namens:
    $ git config --global user.name
Vorname Nachname
    Anzeige der festgelegten E-Mail:
    $ git config --global user.email
s00000@htw-dresden.de
    Auflistung der kompletten Git-Konfiguration:
    $ git config --list
...
user.name=Vorname Nachname
user.email=s00000@htw-dresden.de
Hinweise: Alternative Git-Konfiguration per Git-Kommando

Die Git-Konfiguration kann ebenfalls direkt mit den Git-Kommandos git config [--global] …​ angelegt/bearbeitet, mit git config --list angezeigt und Einstellungen mit git config [--global] --unset …​ entfernt werden.

$ git config --global user.name "Vorname Nachname"
$ git config --global user.email s00000@informatik.htw-dresden.de

Für die Labore der HTW zusätzlich noch ein:

$ git config --global --add safe.directory *
$ git config --global http.proxy http://www-cache.htw-dresden.de:3128
Kommt es unter Windows in der Git Bash bei der Kommunikation mit Ihrem GitHub Repository zu einer Fehlermeldung: ServicePointManager unterstützt keine Proxys mit dem www-cache.htw-dresden.de-Schema, ist der Proxy ohne vorangestelltes http://www-cache.htw-dresden.de:3128 konfiguriert. In dem Falle muss die Proxy Konfiguration, wie oben, neu gesetzt werden.

Aufgabe 2.3 - Repository Clonen

Clonen Sie Ihr Repository htwd-se-example-project an einen geeigneten Platz lokal auf ihren Rechner.

Repository-URL:
https://github.com/<account>/htwd-se-example-project.git

Zu finden auf GitHub in Ihrem Repository beim Klick auf den grünen Code Button im Bereich HTTPS.

Hinweise: Einbindung des Rechenzentrum-Netzlaufwerkes Windows
Windows

  1. Windows Explorer (-Taste+e) öffnen

  2. Seitenleiste: Netzwerk → Rechtsklick: Netzlaufwerk verbinden…​

  3. Netzwerkordner angeben:

    • Ordner: \\samba.htw-dresden.de\sXXXXX → Fertig stellen

  4. Netzwerkanmeldeinformationen eingeben:

    • Benutzername: dom\sXXXXX, Kennwort: …​ → OK

macOS

  1. Finder öffnen

  2. Menü  Gehe zu  Mit Server verbinden …​

  3. Daten eingeben:

    • Ordner: smb://samba.htw-dresden.de/sXXXXX

    • Name: dom\sXXXXX

    • Passwort: …​

Linux todo

…​

Variante - Visual Studio Code (HTTPS):

  1. In Visual Studio Code kann über folgende Varianten ein Git-Rpository geclont werden:

    • View  Source Control → Button Clone Repository

    • View  Command Palette…​ → Git: Clone

    • "Get Started"-Seite → Start: Clone Git Repository…​

    • View  Terminal → cd path/to/folder → git clone …​

      Falls in VS Code schon ein Repository geöffnet ist, kann dies auch in View  SCM über die drei Punkte "…​" im oberen Bereich mit dem Menüeintrag Clone erfolgen.

  2. Im oberen mittleren Bereich geht jetzt ein Eingabefenster auf, in welches Sie Ihre Repository-URL kopieren und Enter drücken.

  3. Wählen Sie noch einen Zielordner, in welchem das Repository als Verzeichnis gespeichert werden soll.

  4. Es erfolgt die Abfrage der Authentifizierung mit GitHub. Hier gibt es jetzt je nach Installation verschiedene Varianten. Entweder wird der Login per GitHub OAuth und der Access Token abgefragt oder Visual Studio Code nutzt seine Access to GitHub Erweiterung.

    Verwenden Sie: GitHub OAuth (oder den in Aufgabe 1.4 zuvor angelegten Access Token)

Die Kommunikation ihres Repositories per https mit GitHub verlangt jedes Mal erneut den Login. Deswegen ist in den Windows-Laboren die Option mit git config --global credential.helper=manager schon in der Git-Konfiguration gesetzt. Damit bleibt Ihr Login für die aktuelle Sitzung gespeichert. Alternativ können Sie auch einen Timeout mit git config --global credential.helper 'cache -timeout=5400' einstellen, so würde der Login 60 Minuten gespeichert bleiben.

Variante - Terminal (HTTPS):

  1. Öffnen Sie ein Terminal (Windows: PowerShell)

  2. Führen Sie darin folgendes Kommando aus und verwenden Sie, bei der Nachfrage zur Authentication-Methode Nummer 2 für den Personal access token von GitHub:

    Clone-Befehl:
    git clone https://github.com/<account>/htwd-se-example-project.git
    Ausgabe Windows - PowerShell:
    > git clone https://github.com/<account>/htwd-se-example-project.git
Cloning into 'htwd-se-example-project'...
Select an authentication method for 'https://github.com/':
  1. Web browser (default)
  2. Personal access token
option (enter for default): 2
Enter GitHub personal access token for 'https://github.com/'...
Token:
remote: Enumerating objects: 10, done.
remote: Counting objects: 100% (10/10), done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 10 (delta 0), reused 4 (delta 0), pack-reused 0
Receiving objects: 100% (10/10), done.
    Ausgabe Linux und macOS - Terminal:
    $ git clone https://github.com/<account>/htwd-se-example-project.git
Klone nach 'htwd-se-example-project' ...
Username for 'https://github.com': <account>
Password for 'https://<account>@github.com':
remote: Enumerating objects: 10, done.
remote: Counting objects: 100% (10/10), done.
remote: Compressing objects: 100% (8/8), done.
remote: Total 10 (delta 0), reused 4 (delta 0), pack-reused 0
Receiving objects: 100% (10/10), done.
Hinweise: Git-Kommunikation per SSH und SSH-Key

Eine weitere Variante wäre die Kommunikation mit GitHub per ssh statt https unter Nutzung eines SSH-Keys. Informationen zur Verwendung findet man unter: Connecting to GitHub with SSH.

Variante - Terminal per SSH (SSH-Key bei GitHub hinterlegt):
$ git clone git@github.com:<account>/htwd-se-example-project.git

Die Verwendung von ssh ist nur in den Linux-Laboren empfohlen, da unter Windows die Einstellungen in den Nutzerprofilen nicht gespeichert werden.

3. Visual Studio Code, AsciiDoc

Aufgabe 3.1 - Konfiguration, Grundsyntax

  1. Öffnen Sie das eben geclonte Projekt, falls noch nicht geschehen, als Ordner in Visual Studio Code: File  Open Folder…​

    In den Linux-Laboren kann Visual Studio Code im Terminal über /opt/VSCode/code gestartet werden.

  2. Erstellen Sie in Ihrem lokalen Repository ein Verzeichnis docs und legen Sie in diesem eine neue leere Datei names Beispieldokumentation.adoc mit Visual Studio Code an. Dies können Sie direkt in Visual Studio Code in der Explorer Ansicht über ein Rechtsklick (Kontextmenü: New File, New Folder) tun.

    Unter Windows muss in Visual Studio Code beim Speichern der Dateityp: All files *.* ausgewählt sein, damit die Datei die Endung .adoc und nicht .adoc.txt bekommt.

  3. Gehen Sie in Visual Studio Code in die Extensions Ansicht und suchen Sie nach AsciiDoc. Installieren Sie, falls noch nicht vorhanden, die Erweiterung AsciiDoc von asciidoctor.

  4. Passen Sie in Visual Studio Code über Preferences (oder Zahnradsymbol)  Settings  Extensions  asciidoc folgende Einstellungen an:

    • Asciidoc > Preview: Use Editor Style: (deaktiviert), für eine neutrale Vorschau

  5. Übernehmen Sie in die Datei Beispieldokumentation.adoc das folgende AsciiDoc-Beispiel und passen Sie den Autor an Ihren Namen und das Datum an das heutige an.

    Infos zur Syntax: AsciiDoc Syntax Quick reference und Asciidoctor User Manual

    Beispieldokumentation.adoc
    = Beispiel-Dokumentation mit AsciiDoc (1)
Vorname Nachname <email> (2)
1.0, 01.09.2019 (3)
:toc: (4)
:toc-title: Inhaltsverzeichnis
// Platzhalter für weitere Dokumenten-Attribute (5)

== Einführung
Dieses Dokument dient im Praktikum als Spielwiese für das Kennenlernen und praktische Üben der Syntax von AsciiDoc.
    1 …​ Titel des Dokumentes
    2 …​ Autor und E-Mail
    3 …​ Version, Datum
    4 …​ Attribut für das Inhaltsverzeichnis
    5 …​ Kommentar, wird später nicht generiert

    Mehrere Autoren werden in eine Zeile getrennt mit ; geschrieben. Besteht ein Autorenname aus mehr als drei Teilen, müssen die Vor- und Nachnamen mit _ jeweils zu einer Gruppe zusammengefasst werden.

    • Bspw: Vorname1_Vorname2 Nachname1_Nachname2 <email> oder Vorname Nachname1_Nachname2_Nachname3 <email>

  6. Aktivieren Sie in Visual Studio Code die parallele Vorschau des AsciiDoc-Dokumentes, siehe Abbildung 1, “Screenshot VSCode mit AsciiDoc”, mit dem dritten Button oben rechts (geteiltes Fenster mit Lupe) oder direkt über folgende Tastenkombination: Ctrl+K V (macOS cmd+K V).

    Screenshot VSCode mit AsciiDoc Vorschau
    Abbildung 1. Screenshot VSCode mit AsciiDoc

  7. Speichern Sie die Änderungen in Ihrer Datei Beispieldokumentation.adoc.

Aufgabe 3.2 - Änderungen in das Repository aufnehmen

Mit den folgenden Schritten nehmen Sie mithilfe von Visual Studio Code die Änderungen in Ihrem Workspace als neue Version in Ihr Git-Repository auf:

Screenshot VSCode mit Git-Integration
Abbildung 2. Screenshot VSCode mit AsciiDoc

  1. Aktivieren Sie über die Sidebar die Versionsverwaltungsansicht Ctrl+Shift+G (View  Source Control)

  2. Im Bereich CHANGES sehen Sie alle neuen U (unbeobachtet), geänderten M (modifiziert) und gelöschten D (gelöscht) Dateien gegenüber ihrer aktuellen Repository-Version. Über das Symbol (git add) bei den einzelnen Dateien oder im Bereich CHANGES können Sie einzelne oder alle Änderungen in den INDEX (Bereich STAGED CHANGES) aufnehmen.

  3. Im Bereich STAGED CHANGES sehen Sie alle im INDEX vorgemerkten geänderten Dateien. Über das Symbol (git rm --cached, git reset) können diese wieder aus dem Index entfernt werden.

  4. Geben Sie in der Textbox (Message …​) einen kurzen Text über die Änderungen die Sie an Ihrem Projekt vorgenommen haben an.

  5. Mit Enter oder über das Symbol (git commit) können Sie jetzt alle im INDEX vorgemerkten Änderungen mit der angegebenen Commit-Message als neue Version in Ihr lokales Repository aufnehmen.

  6. Senden Sie jetzt den Stand Ihres lokalen Repositories zu Ihrem entfernten (remote) Repository auf GitHub. Dies erfolgt über …​  Pull, Push  Push.

    Alternativ über den Sync Changes Button, welcher eine Kombination aus Pull & Push ist.

  7. Schauen Sie sich im Webbrowser auf GitHub Ihre eben gemachten Änderungen in Ihrem Repository an.

Klicken Sie in der Versionsverwaltungsansicht (Source Control) auf den jeweiligen Dateinamen (im Bereich CHANGES, STAGED CHANGES), öffnet sich ein neuer Tab mit einer Gegenüberstellung (diff) Ihrer Bearbeitung zur letzten Version.

Seitenübersicht

Praktika - SE I

Praktika - SE II