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>
This commit is contained in:
parent
ed4eb0d8f3
commit
1dc71a9155
@ -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…
Reference in New Issue
Block a user