Skip to content

Commit

Permalink
user-manual: fix rendering of history diagrams
Browse files Browse the repository at this point in the history
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>
  • Loading branch information
J. Bruce Fields committed Mar 11, 2007
1 parent ed4eb0d commit 1dc71a9
Showing 1 changed file with 21 additions and 4 deletions.
25 changes: 21 additions & 4 deletions Documentation/user-manual.txt
Original file line number Diff line number Diff line change
Expand Up @@ -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
lines drawn with - / and \. Time goes left to right:


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

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


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

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

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

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


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

However, if you prefer to keep the history in mywork a simple series of
commits without any merges, you may instead choose to use
Expand All @@ -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:


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

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
Expand Down Expand Up @@ -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
their branch, with a result something like this:

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

Then suppose you modify the last three commits:

................................................
o--o--o <-- new 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
look like:

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

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
Expand Down Expand Up @@ -2151,21 +2166,23 @@ commit. Git calls this process a "fast forward".

A fast forward looks something like this:

................................................
o--o--o--o <-- old 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
a descendant of the old head. For example, the developer may have
realized she made a serious mistake, and decided to backtrack,
resulting in a situation like:

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


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

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

Expand Down

0 comments on commit 1dc71a9

Please sign in to comment.