Browse Source

user-manual: fix rendering of history diagrams

Asciidoc appears to interpret a backslash at the end of a line as
escaping the end-of-line character, which screws up the display of
history diagrams like

 o--o--o
	\
	 o--...

The obvious fix (replacing "\" by "\\") doesn't work.  The only
workaround I've found is to include all such diagrams in a LiteralBlock.
Asciidoc claims that should be equivalent to a literal paragraph, so I
don't understand why the difference--perhaps it's an asciidoc bug.

Cc: Ramsay Jones <ramsay@ramsay1.demon.co.uk>
Signed-off-by: "J. Bruce Fields" <bfields@citi.umich.edu>
maint
J. Bruce Fields 18 years ago
parent
commit
1dc71a9155
  1. 25
      Documentation/user-manual.txt

25
Documentation/user-manual.txt

@ -437,11 +437,14 @@ We will sometimes represent git history using diagrams like the one
below. Commits are shown as "o", and the links between them with below. Commits are shown as "o", and the links between them with
lines drawn with - / and \. Time goes left to right: lines drawn with - / and \. Time goes left to right:



................................................
o--o--o <-- Branch A o--o--o <-- Branch A
/ /
o--o--o <-- master o--o--o <-- master
\ \
o--o--o <-- Branch B o--o--o <-- Branch B
................................................


If we need to talk about a particular commit, the character "o" may If we need to talk about a particular commit, the character "o" may
be replaced with another letter or number. be replaced with another letter or number.
@ -1928,25 +1931,29 @@ $ git commit
You have performed no merges into mywork, so it is just a simple linear You have performed no merges into mywork, so it is just a simple linear
sequence of patches on top of "origin": sequence of patches on top of "origin":



................................................
o--o--o <-- origin o--o--o <-- origin
\ \
o--o--o <-- mywork o--o--o <-- mywork
................................................


Some more interesting work has been done in the upstream project, and Some more interesting work has been done in the upstream project, and
"origin" has advanced: "origin" has advanced:


................................................
o--o--O--o--o--o <-- origin o--o--O--o--o--o <-- origin
\ \
a--b--c <-- mywork a--b--c <-- mywork
................................................


At this point, you could use "pull" to merge your changes back in; At this point, you could use "pull" to merge your changes back in;
the result would create a new merge commit, like this: the result would create a new merge commit, like this:



................................................
o--o--O--o--o--o <-- origin o--o--O--o--o--o <-- origin
\ \ \ \
a--b--c--m <-- mywork a--b--c--m <-- mywork
................................................
However, if you prefer to keep the history in mywork a simple series of However, if you prefer to keep the history in mywork a simple series of
commits without any merges, you may instead choose to use commits without any merges, you may instead choose to use
@ -1963,9 +1970,11 @@ point at the latest version of origin, then apply each of the saved
patches to the new mywork. The result will look like: patches to the new mywork. The result will look like:




................................................
o--o--O--o--o--o <-- origin o--o--O--o--o--o <-- origin
\ \
a'--b'--c' <-- mywork a'--b'--c' <-- mywork
................................................


In the process, it may discover conflicts. In that case it will stop In the process, it may discover conflicts. In that case it will stop
and allow you to fix the conflicts; after fixing conflicts, use "git and allow you to fix the conflicts; after fixing conflicts, use "git
@ -2073,24 +2082,30 @@ The primary problem with rewriting the history of a branch has to do
with merging. Suppose somebody fetches your branch and merges it into with merging. Suppose somebody fetches your branch and merges it into
their branch, with a result something like this: their branch, with a result something like this:


................................................
o--o--O--o--o--o <-- origin o--o--O--o--o--o <-- origin
\ \ \ \
t--t--t--m <-- their branch: t--t--t--m <-- their branch:
................................................


Then suppose you modify the last three commits: Then suppose you modify the last three commits:


................................................
o--o--o <-- new head of origin o--o--o <-- new head of origin
/ /
o--o--O--o--o--o <-- old head of origin o--o--O--o--o--o <-- old head of origin
................................................


If we examined all this history together in one repository, it will If we examined all this history together in one repository, it will
look like: look like:


................................................
o--o--o <-- new head of origin o--o--o <-- new head of origin
/ /
o--o--O--o--o--o <-- old head of origin o--o--O--o--o--o <-- old head of origin
\ \ \ \
t--t--t--m <-- their branch: t--t--t--m <-- their branch:
................................................


Git has no way of knowing that the new head is an updated version of Git has no way of knowing that the new head is an updated version of
the old head; it treats this situation exactly the same as it would if the old head; it treats this situation exactly the same as it would if
@ -2151,9 +2166,11 @@ commit. Git calls this process a "fast forward".


A fast forward looks something like this: A fast forward looks something like this:


................................................
o--o--o--o <-- old head of the branch o--o--o--o <-- old head of the branch
\ \
o--o--o <-- new head of the branch o--o--o <-- new head of the branch
................................................




In some cases it is possible that the new head will *not* actually be In some cases it is possible that the new head will *not* actually be
@ -2161,11 +2178,11 @@ a descendant of the old head. For example, the developer may have
realized she made a serious mistake, and decided to backtrack, realized she made a serious mistake, and decided to backtrack,
resulting in a situation like: resulting in a situation like:


................................................
o--o--o--o--a--b <-- old head of the branch o--o--o--o--a--b <-- old head of the branch
\ \
o--o--o <-- new head of the branch o--o--o <-- new head of the branch

................................................



In this case, "git fetch" will fail, and print out a warning. In this case, "git fetch" will fail, and print out a warning.



Loading…
Cancel
Save