docs_src

AsciiDoc Sources

This folder contains the AsciiDoc sources of the English translation of the Git-Buch.

STATUS — Polishing the draft-translation (created via DeepL) and adapting images.

---

Table of Contents

• Folder Contents
• Developers' Notes
  • HTML Preview Document
  • Methodology Notes
• Sources Adaptation
  • Upstream Correspondences
• Look-Up Tables
  • Footnotes
  • Figures

---

Folder Contents

• /images/ — required book images.
• Git-Book_Preview.html — developer's HTML5 book preview (untracked), built via rake preview.
• Git-Book_Chunker-Input.html — intermediate doc (untracked) for website chunking, built via rake publish.
• gitbuch.asciidoc — main book source that imports all others:
  • gitbuch_preamble.asciidoc — preamble.
  • gitbuch_00.adoc — Preface
  • gitbuch_01.adoc — 1. Introduction and First Steps
  • gitbuch_02.adoc — 2. The Basics
  • gitbuch_03.adoc — 3. Practical Version Control
  • gitbuch_04.adoc — 4. Advanced Concepts
  • gitbuch_05.adoc — 5. Distributed Git
  • gitbuch_06.adoc — 6. Workflows
  • gitbuch_07.adoc — 7. Git Servers
  • gitbuch_08.adoc — 8. Git Automation
  • gitbuch_09.adoc — 9. Interacting with Other Version Control Systems
  • gitbuch_10.adoc — 10. Shell-Integration
  • gitbuch_11.adoc — 11. GitHub
  • gitbuch_12.adoc — App. A. Installation
  • gitbuch_13.adoc — App. B. Repository Structure
  • gitbuch_custom-attributes.adoc — attributes definitions for inline substitutions.
  • gitbuch_footnotes.adoc — all the book's footnotes externalized via attributes.

Developers' Notes

To build and publish the book type

rake publish

which will generate:

1. The online book edition — served on the web via GHPages as a multi-page chunked document:

   ../docs/index.html

2. The HTML book edition — for end users download, as a fully standalone single-file document:

   ../docs/download/Git-Book.html

The generated documents are tracked by Git, so don't include them in your commits or pull requests unless you're intentionally willing to update them.

HTML Preview Document

To quickly preview your changes to the document, just type

rake

which will generate the Git-Book_Preview.html document in this folder.

This preview document is ignored by Git and will not end up in your commits. Furthermore, it offers a few advantages over the published HTML book:

• NO EMBEDDED IMAGES — It doesn't embed images via Data URIs, so if you change any image you'll only need to refresh the HTML document in the browser to see changed images, without having to rebuild the HTML doc from source.
• DEEPER TOC — Its TOC is always set to maximum level, so you can see every section in the TOC sidebar.

Methodology Notes

The translation work for each book section is divided into two separate stages:

• Draft
• Polishing

In the draft stage the automated translation via DeepL is added to the document with minor adjustments, and the focus is on restoring all the lost formatting styles, footnotes and cross references, translating anchors' identifiers and validating all links:

• Update URLs of projects which have been moved.
• In case of dead links, point to the archived page/site on Wayback Machine.
• Update all links to https://, when possible.

During this stage the original German text is kept inside comment blocks next to the English translation, to provide a quick reference to compare the ongoing translation with the original. All Asciidoctor macros are expanded in the German text, to reveal the original text of cross references and footnotes numbers.

In the polishing stage the translation is revised and polished until considered good to go — at that point, the comment blocks with the original German text can be removed.

Keeping the two stages separate is practical because the draft stage concerns mainly the technical aspects of adapting the automated translation to the AsciiDoc standard, and fixing all formatting and logistic aspects of the document, so once these are out of the way the document can move on to the polishing stage, where the translators can focus on the English text, without having to worry about formatting issues and other technicalities.

Sources Adaptation

The upstream repository used AsciiDoc (Python) to build the Git-Buch, whereas this repository uses Asciidoctor (Ruby), therefore some adaptations were applied to the sources formatting and conventions due to slight differences between the two AsciiDoc implementations and in order to benefit from the additional features of Asciidoctor.

All sources were renamed using a two-digits counter indicating their order of appearance in the book; furthermore all files extensions where changed from .txt to .adoc, with the exception of the main entry file which assigned the .asciidoc extension to distinguish it from the other sources which are imported via the include:: directive.

Some unbalanced block delimiters errors had to be fixed in the original sources for they were breaking the document.

Upstream Correspondences

The following table shows the correspondence between the current sources and their original counterparts on the upstream repository.

source file	adapted from	chapter title / file description
gitbuch.asciidoc	git.txt	main entry file.
gitbuch_preamble.asciidoc	none	preamble
gitbuch_00.adoc	vorwort.txt	Preface
gitbuch_01.adoc	erste_schritte.txt	1. Introduction and First Steps
gitbuch_02.adoc	grundlagen.txt	2. The Basics
gitbuch_03.adoc	praxis.txt	3. Practical Version Control
gitbuch_04.adoc	advanced.txt	4. Advanced Concepts
gitbuch_05.adoc	remote.txt	5. Distributed Git
gitbuch_06.adoc	workflows.txt	6. Workflows
gitbuch_07.adoc	server.txt	7. Git Servers
gitbuch_08.adoc	automatisierung.txt	8. Git Automation
gitbuch_09.adoc	zusammenspiel.txt	9. Interacting with Other Version Control Systems
gitbuch_10.adoc	shell.txt	10. Shell-Integration
gitbuch_11.adoc	github.txt	11. GitHub
gitbuch_12.adoc	installation.txt	App. A. Installation
gitbuch_13.adoc	gitdir.txt	App. B. Repository Structure

Look-Up Tables

A few tables to quickly look-up the book's footnotes, figures, and other useful info.

Footnotes

There are 156 footnotes in the book.

chapter	footnotes
Preface	1-7
1. Introduction and First Steps	8-11
2. The Basics	12-28
3. Practical Version Control	29-53
4. Advanced Concepts	54-64
5. Distributed Git	65-87
6. Workflows	88-91
7. Git Servers	92-105
8. Git Automation	106-116
9. Interacting with Other Version Control Systems	117-133
10. Shell-Integration	134-137
11. GitHub	138-150
App. A. Installation	151-153
App. B. Repository Structure	154-156

Figures

NOTE — Image filenames are translated too, not just their text contents.

figure	image file	image type	chapter
Fig. 1	index.svg	DIA diagram	Ch. 2
Fig. 2	objektmodell-programm-crop.png	dir listing	Ch. 2
Fig. 3	sha.svg	DIA diagram	Ch. 2
Fig. 4	git-objects.svg	DIA diagram	Ch. 2
Fig. 5	git-objects-hierarchy.svg	DIA diagram	Ch. 2
Fig. 6	repository-content.svg	DIA diagram	Ch. 2
Fig. 7	commit-graph.svg	DIA diagram	Ch. 2
Fig. 8	commit-graph-with-refs.svg	DIA diagram	Ch. 2
Fig. 9	gitk-basic.png	screenshot	Ch. 3
Fig. 10	commit.svg	DIA diagram	Ch. 3
Fig. 11	relative-refs.svg	DIA diagram	Ch. 3
Fig. 12	tags.svg	DIA diagram	Ch. 3
Fig. 13	tag-screenshot.png	screenshot	Ch. 3
Fig. 14	describe-screenshot.png	screenshot	Ch. 3
Fig. 15	merge-base-commit.svg	DIA diagram	Ch. 3
Fig. 16	ff-before.svg	DIA diagram	Ch. 3
Fig. 17	ff-after.svg	DIA diagram	Ch. 3
Fig. 18	ff-no-ff-vergleich.png	screenshot	Ch. 3
Fig. 19	meld-example.png	screenshot	Ch. 3
Fig. 20	revision-list-commit-graph-gitk.png	screenshot	Ch. 3
Fig. 21	gitk.png	screenshot	Ch. 3
Fig. 22	rebase-before.svg	DIA diagram	Ch. 4
Fig. 23	rebase-after.svg	DIA diagram	Ch. 4
Fig. 24	screenshot-rebase-vorher.png	screenshot	Ch. 4
Fig. 25	screenshot-rebase-nachher.png	screenshot	Ch. 4
Fig. 26	rebase-onto-before.svg	DIA diagram	Ch. 4
Fig. 27	rebase-onto-after.svg	DIA diagram	Ch. 4
Fig. 28	git-gui-blame.png	screenshot	Ch. 4
Fig. 29	stash-screenshot.png	screenshot	Ch. 4
Fig. 30	central-workflow.svg	DIA diagram	Ch. 5
Fig. 31	clone.svg	DIA diagram	Ch. 5
Fig. 32	remote-tracking-gitk.png	screenshot	Ch. 5
Fig. 33	fetch.svg	DIA diagram	Ch. 5
Fig. 34	pull.svg	DIA diagram	Ch. 5
Fig. 35	pull-rebase.svg	DIA diagram	Ch. 5
Fig. 36	push.svg	DIA diagram	Ch. 5
Fig. 37	integration-manager-workflow.svg	DIA diagram	Ch. 5
Fig. 38	gitk-screen-format-patch.png	screenshot	Ch. 5
Fig. 39	mail-thread.png	screenshot	Ch. 5
Fig. 40	patches-via-email.svg	DIA diagram	Ch. 5
Fig. 41	branch-model.svg	DIA diagram	Ch. 6
Fig. 42	gitweb-overview.png	screenshot	Ch. 7
Fig. 43	gitweb-commitdiff.png	screenshot	Ch. 7
Fig. 44	cgit-overview.png	screenshot	Ch. 7
Fig. 45	cgit-commitdiff.png	screenshot	Ch. 7
Fig. 46	tux-diff.png	screenshot	Ch. 8
Fig. 47	svn-stdlayout-crop.png	dir listing	Ch. 9
Fig. 48	svn-nonstdlayout-crop.png	dir listing	Ch. 9
Fig. 49	svn-branches-crop.png	dir listing	Ch. 9
Fig. 50	git-branches-crop.png	dir listing	Ch. 9
Fig. 51	git-convert-refs-before.png	screenshot	Ch. 9
Fig. 52	git-convert-refs-after.png	screenshot	Ch. 9
Fig. 53	git-svn-tag-fix-before.png	screenshot	Ch. 9
Fig. 54	git-svn-tag-fix-after.png	screenshot	Ch. 9
Fig. 55	git-svn-merge-demo.png	screenshot	Ch. 9
Fig. 56	svn-rebase.svg	DIA diagram	Ch. 9
Fig. 57	svn-dcommit.svg	DIA diagram	Ch. 9
Fig. 58	github-gollum.png	screenshot	Ch. 11
Fig. 59	github-workflow.svg	DIA diagram	Ch. 11
Fig. 60	github-network.png	screenshot	Ch. 11
Fig. 61	github-download.png	screenshot	Ch. 11
Fig. 62	github-image-diff-2up.png	screenshot	Ch. 11
Fig. 63	github-image-diff-swipe.png	screenshot	Ch. 11
Fig. 64	git-dir-crop.png	dir listing	App. B