Dieses Dokument ist ein einfacher, einfacher Leitfaden, der Sie von „Was in aller Welt ist Git?“ begleitet. zu „Jeder sollte mein brandneues Charakterblatt benutzen!“ so schnell wie möglich, ohne zu versuchen, Ihnen alle Feinheiten beizubringen, zu denen das System fähig ist. Git ist eine Versionskontrollsoftware, aber in diesem Handbuch wird völlig außer Acht gelassen, wie Sie damit Ihre Änderungen verfolgen können, und sich ausschließlich auf das Verschieben Ihrer Updates in die Master-Roll20-Repositorys konzentrieren. Der Abschnitt „Weitere Informationen“ enthält Links zu Anleitungen zur Funktionsweise von Git/GitHub, die allgemeiner Natur sind.
Was ist Git/GitHub?
Gitist eine Software, die Sie lokal auf Ihrem Computer installieren und die die Versionskontrolle für Sie übernimmt. GitHubist ein Hosting-Dienst fürGitRepositorys. Sie sind also nicht dasselbe:Gitist das Tool,GitHubist der Dienst für Projekte, dieGitverwenden. Kurzvergleich.
Es gibt verschiedene Möglichkeiten, Git zu verwenden. Git ist sehr leistungsfähig, aber um das Beste daraus zu machen, müssen Sie lernen, wie man die Befehlsshell (xkcd comic) verwendet. Im Abschnitt „Weitere Informationen“ unten finden Sie weitere Informationen zur Befehlsshell für Interessierte. Allerdings kann alles, was dieses Dokument Ihnen zeigt, nur mit der GitHub-Desktop-GUI (sehr gut, um die Festplatte Ihres Computers mit Ihrem Repository synchron zu halten – siehe „Klonen Sie Ihr Repository“ unten) und den beiden GitHub-Webtools erledigt werden Hierbei handelt es sich um vereinfachte Tools zur Verwendung des zugrunde liegenden Git.
GitHub einrichten
Erstelle deinen Account
Um GitHub nutzen zu können, benötigen Sie ein Konto auf deren Website. Sie können ein kostenpflichtiges Konto oder ein kostenloses Konto erstellen. Sofern Sie nicht vorhaben, eine große Anzahl von Projekten zu erstellen, die Sie nicht mit der Welt teilen möchten, gibt es keinen Grund, ein kostenpflichtiges Konto zu erstellen: Der einzige Unterschied zwischen den verschiedenen Preisstufen besteht in der Anzahl der privaten Repositories, die Ihnen erlaubt sind haben. Jeder, auch kostenlose Konten, erhält eine unbegrenzte Anzahl öffentlicher Repositories.
Sie werden sich mit den Master-Roll20-Repositories für roll20-character-sheets und/oder roll20-api-scripts befassen, bei denen es sich um öffentliche Repositories handelt. Sie werden auch einen Fork dieser Repositories erstellen, der genauso gut auch öffentlich sein könnte, sodass Sie für Ihre Roll20-Nutzung lediglich ein kostenloses Konto benötigen.
FORK das offizielle Roll20-Repository
EinForkist eine Kopie eines Repositorys. Durch die Verzweigung eines Repositorys können Sie frei mit Änderungen experimentieren, ohne das ursprüngliche Projekt zu beeinträchtigen.
Das Forken ist mit den GitHub-Webtools einfach durchzuführen. Klicken Sie im offiziellen Repository unterhttps://github.com/Roll20/roll20-character-sheetsoderhttps://github.com/Roll20/roll20-api-scriptsauf die Schaltfläche Fork geeignet. Dadurch wird eine Kopie dieses Repositorys in Ihrem Konto erstellt, an der Sie nach Belieben Änderungen vornehmen können. können das Repository so oft, wie Sie möchten, aber Sie benötigen nurum es einmal zu teilen. Dieses neue Repository hat eine Adresse, die mit der des Originals identisch ist, außer dass „Roll20“ nicht im Stammverzeichnis, sondern im Stammverzeichnis Ihres roll20-Kontonamens gespeichert ist.
Wenn Sie mit einem anderen Benutzer am selben Blatt oder Skript arbeiten, ist es möglicherweise eine gute Idee, die Einstellungen Ihres neuen Repositorys aufzurufen und ihn als Mitarbeiter hinzuzufügen. Die Einzelheiten zum Hinzufügen eines Mitarbeiters oder zum Arbeiten mit einem Mitarbeiter gehen jedoch über den Rahmen dieses Tutorials hinaus.
Wenn Sie mit dem Git-Versionskontrollsystem vertraut sind, sollten Sie keine weiteren Informationen benötigen, um die Übermittlung Ihres Charakterblatts abzuschließen. Alle anderen, lesen Sie weiter!
KLONEN Sie Ihr Repository
KlonenEin Repository erstellt ebenfalls eine Kopie, aber ein geklontes Repository wird als Arbeitskopie verwendet und befindet sich wie normale Ordner und Dateien auf der Festplatte Ihres lokalen Computers. Git verwaltet einen Link – standardmäßig mit dem Namen „Origin“ – zwischen den Ordnern und dem Repository, aus dem es geklont wurde.
Für Git-Anfänger wird dringend empfohlen, je nach Betriebssystem entwederGitHub für WindowsoderGitHub für Macherunterzuladen und zu installieren. Diese werden in diesem Dokument im Folgenden als „GitHub Desktop“ oder „die Desktop-App“ bezeichnet. Die GitHub-Desktopanwendungen bieten nicht nur eine einfache Möglichkeit, die Git-Versionskontrolle auf Ihrem Computer zu installieren und einzurichten, sondern ermöglichen auch die einfache Verknüpfung mit Ihrem GitHub-Benutzerkonto. Es informiert Sie, wenn Ihre Dateien auf Ihrem Computer mit Ihrem Repository auf GitHub veraltet sind, und ermöglicht Ihnen eine einfache Synchronisierung der beiden.
Wenn Sie die GitHub-Anwendung zum ersten Mal ausführen, werden Sie aufgefordert, sich bei Ihrem GitHub-Konto anzumelden. Klicken Sie dann oben links auf das große Pluszeichen, um Ihr Repository zu klonen. Wenn Sie das Repository klonen, werden Sie aufgefordert, einen Speicherort für die Dateien auszuwählen. Stellen Sie sicher, dass Sie einen Ort auswählen, den Sie leicht finden können. Sie müssen wissen, wo er sich befindet! Wenn Sie einen neuen Computer erhalten, ist die Installation des GitHub-Desktops und das Klonen Ihres Repositorys der einzige Schritt, der wiederholt werden muss.
Die Desktop-App verfügt außerdem über die einfachste Oberfläche zum Verwalten von Filialen. Wenn Sie Zweige innerhalb der Desktop-Anwendung wechseln, werden Dateien hinzugefügt/entfernt/geändert, sodass sie mit dem letzten Commit übereinstimmen, der in dem Zweig durchgeführt wurde, zu dem Sie gewechselt haben.
Wenn Sie die GitHub-Anwendung nicht verwenden, finden Sie die Klon-URL für Ihr Repository auf der Seite für Ihr Repo. GitHub bietet sowohl SSH- als auch HTTPS-Klon-URLs sowie eine Subversion-Checkout-URL. Die Details zum manuellen Klonen Ihres Repos gehen jedoch über den Rahmen dieses Handbuchs hinaus.
GitHub Forking-Workflow
Die obige Einrichtung wird nur einmal durchgeführt. Im folgenden Abschnitt werden die Verfahren beschrieben, die jedes Mal befolgt werden sollten, wenn Sie ein Update an Roll20 senden möchten.
Synchronisieren Sie Ihre Dateien mit Roll20
Wenn Sie Ihr Repository vor ein paar Minuten geforkt und geklont haben, ist es immer noch synchron. Wenn Sie jedoch nach vielen Wochen oder Monaten zu Ihrem Repository zurückkehren, wurden einige der Zeichenblätter oder API-Skripte aktualisiert. Es besteht die Möglichkeit, dass derjenige, den Sie ändern möchten, darunter ist. In diesem Fall müssen Sie sicherstellen, dass Sie mit der aktuellsten Version der Dateien arbeiten, die Sie ändern möchten. Sie müsseneinenFork erstellen noch Ihr Repository erneut klonen. Sie müssen Ihren Fork mit Master aktualisieren. Lesen Sie die unten verlinkte Anleitung zur Synchronisierung
Anstatt eine Synchronisierung durchzuführen, ob dies erforderlich ist oder nicht, möchten Sie möglicherweise zunächst prüfen, ob Sie die Projekte, an denen Sie arbeiten, synchronisieren müssen. Eine einfache Überprüfung besteht darin, sich die Dateien im Roll20-Repository anzusehen und das Datum der letzten Änderung anzuzeigen. Eine andere Möglichkeit besteht darin, die Dateien dort zu öffnen und ein„Diff“-Dienstprogrammfür sie und Ihre neueste Version auszuführen. Überprüfen Sie, ob für die Dateien, die Sie aktualisieren möchten, Pull-Anfragen ausstehen. Wenn die spezifischen Dateien, die Sie ändern werden, seit der letzten Synchronisierung unverändert geblieben sind, ist die Durchführung einer vollständigen Synchronisierung aller Dateien optional.
Eine andere Möglichkeit besteht darin, einfach alle Updates aus dem Master-Roll20-Repository abzurufen. Dadurch werden alle Aktualisierungen abgerufen, die andere Benutzer seit der letzten Synchronisierung an den roll20-Repositorys vorgenommen haben (einschließlich einer Reihe von Zeichenblättern oder API-Skripten, die Sie möglicherweise nicht interessieren). Dieser Link enthälteine Anleitung zum Synchronisieren Ihres Repositorys mit Original. Wenn Sie damit fertig sind, sollten die Dateien im Roll20-Master-Repository, Ihrem eigenen Repository und Ihrer Festplatte alle gleich sein. Stellen Sie sicher, dass Sie auch Ihre roll20-Kampagne aktualisieren.
Machen Sie einen Zweig
Es wird empfohlen, für jedes einzelne Projekt (Zeichenblatt oder API-Skript) und für jedes einzelne Update einen neuen Zweig zu erstellen. Wenn Sie beispielsweise zwei verschiedene API-Skripte gleichzeitig aktualisieren möchten, erstellen Sie für jedes Skript eine Verzweigung. Wenn Sie sich einige Wochen später dazu entschließen, weitere Änderungen am selben Skript vorzunehmen, erstellen Sie einen neuen Zweig für das neuere Update. Als Faustregel gilt: Erstellen Sie für jede Pull-Anfrage einen neuen Branch.
Die Desktop-App verfügt außerdem über die einfachste Oberfläche zum Verwalten von Filialen. Wählen Sie im Menü oben einfach „Filiale/Neue Filiale“ aus. Wenn Sie Zweige innerhalb der Desktop-Anwendung wechseln (in der zweiten Zeile können Sie das Repository, an dem Sie arbeiten, und den aktuellen Zweig wechseln), werden Dateien auf Ihrer Festplatte hinzugefügt/entfernt/geändert, sodass sie mit dem zuletzt durchgeführten Commit übereinstimmen aus der Filiale, zu der Sie gewechselt haben.
COMMIT Ihre Änderungen und PUSH Ihre Commits
Wenn SieÄnderungen festschreiben, speichern Sie eine Aufzeichnung aller Änderungen sowie eine für Menschen lesbare Beschreibung dessen, was Sie auf Ihrem lokalen Computer vorgenommen haben.
AnschließendpushenSie Ihre Commits in Ihr Repository.
Sobald Sie eine Arbeitskopie Ihres Repositorys geklont haben, können Sie Änderungen daran vornehmen. Dazu gehört das Erstellen eines neuen Ordners für Ihr Charakterblatt oder API-Skript und das Hinzufügen des Quellcodes oder das Vornehmen von Änderungen an bereits vorhandenen Dateien.
Viele Leute führen bei der Entwicklung von Roll20-Skripten oder Charakterblättern die gesamte eigentliche Bearbeitung in einem Texteditor (z. B. Notepad++) durch. Sie können die Dateien auf Ihrer Festplatte (die im Schritt „Klonen“ erstellt wurden) einfach in einem beliebigen Texteditor öffnen und die Änderungen im Editor vornehmen. Wenn Sie den Code auf Roll20 ausführen möchten, drücken Sie Strg/A und Strg/C, um den gesamten Text auszuwählen und in die Zwischenablage zu kopieren. Fügen Sie es dann in das richtige Roll20-Kampagnenfeld ein. Wenn zusätzliche Änderungen erforderlich sind (z. B. Debugging), ist es oft am einfachsten, einen kontinuierlichen Zyklus aus Bearbeiten, Kopieren, Einfügen und Testen durchzuführen.
Wenn Sie dem Texteditor befehlen, Ihre Änderungen zu speichern, schreibt er Ihre Änderungen schließlich in die Datei, die Sie bearbeitet haben, und GitHub Desktop erkennt, dass sich die von Ihnen bearbeitete Datei geändert hat, und zeigt links den Namen der Datei an, die sich geändert hat Im rechten Fensterbereich wird eine Zusammenfassung der festgestellten Unterschiede zwischen der aktuellen Speicherung und dem letzten durchgeführten Commit angezeigt. Da diese Änderungen jedoch nur erkannt wurden, zeichnet GitHub diese Änderungen erst auf, wenn Sie sie festschreiben. Die Git-Experten empfehlen häufiges Commit, da Sie durch das Commit ein externes Backup Ihrer Arbeit und eine Aufzeichnung jedes Commits erhalten.
Ohne eine Zusammenfassung können Sie keine Änderungen festschreiben, die Beschreibung ist jedoch optional
Sich zu verpflichten ist sehr einfach. Die Desktop-App hat bereits die gesamte Arbeit erledigt, um zu ermitteln, was festgeschrieben werden muss. Geben Sie einen Titel für die Änderungen und(optionalein, geben Sie eine längere Beschreibung ein und übernehmen Sie die Änderung, indem Sie auf die Schaltfläche „Übernehmen an (Zweig)“ klicken. Stellen Sie sicher, dass Sie Ihre Commits in Ihrem Arbeitszweig und nicht in Ihrem Hauptzweig vornehmen. Durch häufige Commits erhalten Sie einen detaillierten Verlauf der von Ihnen vorgenommenen Änderungen, im Gegensatz zu einem einzelnen Commit mit allem, wenn Sie fertig sind. Beachten Sie, dass die Länge der Zusammenfassung begrenzt ist. Wenn Sie jedoch das Limit überschreiten, wird Ihre Nachricht automatisch in die längere Beschreibung übergehen. Sie können dies daran erkennen, dass der Text im Feld „Zusammenfassung“ grau wird.
Sobald Sie den Commit durchführen, sollte auf dem GitHub-Desktop ein großer Hinweis angezeigt werden, dass keine lokalen Änderungen vorliegen. Es sollte auch vorschlagen, dass Sie Ihr Commit zum Ursprung verschieben. Alternativ könnte Ihnen vorgeschlagen werden, „Zweig veröffentlichen“ zu wählen. Durch das Festschreiben werden Ihre Änderungen weiterhin nur auf Ihrem Computer gespeichert. Um diese Änderungen auf GitHub zu übertragen, müssen Sie sie an Ihren Ursprungsort übertragen, wobei das Repository online gespeichert wird. Klicken Sie einfach auf die Schaltfläche „Push Origin“ oder „Publish Branch“. Alternativ sollte zu jedem Zeitpunkt, an dem Ursprung und Klon veraltet sind, oben rechts eine sehr schlecht beschriftete Schaltfläche mit einer Zahl und einem Pfeil angezeigt werden. Das sollte neben anderen netten Dingen alles zwischen Ihrem Repository und dem Klon synchronisieren, sodass Sie das stattdessen pushen können. Oben im Desktop-Tool erledigt auch der Dropdown-Menüpunkt „Repository – Push“ die Arbeit.
Fahren Sie mit der Bearbeitung fort und nehmen Sie Commits vor, bis Ihre Änderungen abgeschlossen sind und Sie den Code getestet und debuggt haben, der zur Übermittlung bereit ist, damit Sie ihn für den Rest von roll20 genießen können. Sie können nun die Roll20-Site-Administratoren auffordern, Ihre Änderungen in das offizielle Roll20-Master-Repository zu „ziehen“.
Erstellen Sie eine PULL-Anfrage
Wie der Name schon sagt, ist einPulldas Gegenteil eines Push. Anstatt dass ein kopiertes Repository Commits an das Original sendet, fordert das Original Commits von der Kopie an.
Auf der Webseite Ihres Repositorys gibt es eine grüne Schaltfläche mit der Aufschrift „Vergleichen, überprüfen, Pull-Anfrage erstellen“, wenn Sie mit der Maus darüber fahren. Über diese Schaltfläche gelangen Sie zu einer Seite, auf der Sie eine Pull-Anfrage erstellen können. Wenn es Unterschiede zwischen Ihrem Repository („Kopf“) und der Roll20-Version des Repositorys („Basis“) gibt, werden diese hier angezeigt. (Beachten Sie, dass Sie ändern können, was sowohl als Kopf als auch als Basis verwendet werden soll, indem Sie auf die Schaltfläche „Bearbeiten“ in der Nähe klicken.) Da sich Ihre Änderungen alle in Ihrem Arbeitszweig und nicht in Ihrem Hauptzweig befinden, möchten Sie, dass Ihre Pull-Anfrage von Ihrem Arbeitszweig kommt.
Da Sie keine Mitarbeiterberechtigungen für das Repository von Roll20 haben, können Sie die Pull-Aktion nicht selbst durchführen, aber Sie könnenandere Person bitten, den Pull durchzuführen. Klicken Sie auf die große grüne Schaltfläche mit der Aufschrift „Pull-Anfrage erstellen“ und eine Pull-Anfrage wird im Basis-Repository geöffnet. Die dazu berechtigten Personen (z. B. die Roll20-Entwickler) können die Pull-Anfrage sowie den Inhalt der Änderungen prüfen vorgeschlagen, und führen Sie die Anfrage dann in das offizielle Repository ein.
Der Übersichtlichkeit halber geben Sie bitte im Pull-Request den Namen des Blatts an, für das Sie Änderungen vorgenommen haben, z. B. „[Dungeondivers 3rd Edition] hat einen fehlerhaften Machtwurf behoben“ .
Denken Sie bei der Einreichung von Charakterblättern daran,sheet.jsonund ein Vorschaubild beizufügen – weitere Informationen finden Sie in der Readme-Datei. Denken Sie bei der Übermittlung von API-Skripten daran,script.jsoneinzuschließen – weitere Informationen finden Sie in der Readme-Datei. Vorausgesetzt, dass alles korrekt ist, sollte Ihr Blatt oder Skript zur Dateigenehmigt.yamlhinzugefügt werden und für alle Benutzer verfügbar sein!
Einmal pro Woche bearbeitet Roll20 alle verfügbaren Blattanfragen. In diesem Fall erhalten Sie eine E-Mail von GitHub. Mit dieser E-Mail werden Sie entweder darüber informiert, dass zu Ihrer Anfrage ein Kommentar zu einem Problem hinterlassen wurde, das bei Ihrer Einreichung entdeckt wurde, ODER ob Ihr Blatt wie erwartet zusammengeführt wurde und Ihre Anfrage geschlossen wurde (weil sie erfolgreich abgeschlossen wurde).
Nehmen Sie Änderungen an Ihrer PULL-Anfrage vor
Wenn Sie einen Pull-Request erstellen und dann & zusätzliche Änderungen an Ihrem Repository/Branch festschreiben, bevor der Pull-Request zusammengeführt wird, werden diese neuen Änderungen automatisch aktualisiert/in den ursprünglichen Pull-Request aufgenommen; Es ist kein zweiter Zug erforderlich.
Aufräumen
Löschen Sie KEINEN Branch, bis alle Pull-Requests von diesem Branch abgeschlossen und geschlossen sind. Eigentlich hat man es nie eilig, einen Zweig überhaupt zu löschen. Sie schaden nicht, solange Sie daran denken, jeden Zweig nur einmal zu verwenden.
Die GitHub-Software empfiehlt Ihnen, Ihren Branch wieder mit dem Master zusammenzuführen. Dies ist ein Schritt, der bei anderen Workflows erforderlich ist, jedoch nicht beim Forking-Workflow, den wir verwenden. Stattdessen empfehlen wir als ersten Schritt zur Vorbereitung Ihres nächsten Updates, Ihren Fork mit dem roll20-Original zu synchronisieren. Dadurch werden die Aktualisierungen, die Sie gerade vorgenommen haben (sowie alle Änderungen, die andere vorgenommen haben), in Ihren Fork übernommen.
Daher sind keine Aufräumarbeiten erforderlich.
Mehr Info
- Tipps zur Verwendung von Github(Roll20-Forumsthread)
- Der GitHub-Workflow (Visualisierung)(nicht der Flow, den wir verwenden, aber eine gute Visualisierung) undForking-Workflow(was wir verwenden)
- Git – Der einfache Leitfaden (Befehlszeilentool)von Roger Dudler
- GitHub-Workflow (GitHub Desktop)22.06.16
Git und Github für Dichter Youtube-Tutorial
10–20 Minuten lange Videos für technisch nicht versierte Personen, die die Grundlagen von Git und Github vermitteln, zeigen, wie man mit Github im Browser arbeitet, aber auch eine Einführung in die Verwendung der Befehlszeile geben. Es wurde im Jahr 2016 hergestellt, scheint aber auf den ersten Blick nicht veraltet zu sein (März 2019)
- 1,2 Zweige12 Min
Git und Github für Dichter (über die Grundlagen hinaus)
- 1.4 GitHub-Probleme12 Min
- 1.10 Git Remotes14 Min