Add basic git-subtree manpage in asciidoc format.

.gitignore

@@ -1 +1,3 @@
 *~
+git-subtree.xml
+git-subtree.1

Makefile

@@ -0,0 +1,18 @@
+default:
+	@echo "git-subtree doesn't need to be built."
+	@echo
+	@echo "Try: make doc"
+	@false
+
+doc: git-subtree.1
+
+%.1: %.xml
+	xmlto -m manpage-normal.xsl  man $^
+
+%.xml: %.txt
+	asciidoc -b docbook -d manpage -f asciidoc.conf \
+		-agit_version=1.6.3 $^
+
+clean:
+	rm -f *~ *.xml *.html *.1
+	rm -rf subproj mainline

asciidoc.conf

@@ -0,0 +1,91 @@
+## linkgit: macro
+#
+# Usage: linkgit:command[manpage-section]
+#
+# Note, {0} is the manpage section, while {target} is the command.
+#
+# Show GIT link as: <command>(<section>); if section is defined, else just show
+# the command.
+
+[macros]
+(?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
+
+[attributes]
+asterisk=&#42;
+plus=&#43;
+caret=&#94;
+startsb=&#91;
+endsb=&#93;
+tilde=&#126;
+
+ifdef::backend-docbook[]
+[linkgit-inlinemacro]
+{0%{target}}
+{0#<citerefentry>}
+{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
+{0#</citerefentry>}
+endif::backend-docbook[]
+
+ifdef::backend-docbook[]
+ifndef::git-asciidoc-no-roff[]
+# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
+# v1.72 breaks with this because it replaces dots not in roff requests.
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+ifdef::doctype-manpage[]
+&#10;.ft C&#10;
+endif::doctype-manpage[]
+|
+ifdef::doctype-manpage[]
+&#10;.ft&#10;
+endif::doctype-manpage[]
+</literallayout>
+{title#}</example>
+endif::git-asciidoc-no-roff[]
+
+ifdef::git-asciidoc-no-roff[]
+ifdef::doctype-manpage[]
+# The following two small workarounds insert a simple paragraph after screen
+[listingblock]
+<example><title>{title}</title>
+<literallayout>
+|
+</literallayout><simpara></simpara>
+{title#}</example>
+
+[verseblock]
+<formalpara{id? id="{id}"}><title>{title}</title><para>
+{title%}<literallayout{id? id="{id}"}>
+{title#}<literallayout>
+|
+</literallayout>
+{title#}</para></formalpara>
+{title%}<simpara></simpara>
+endif::doctype-manpage[]
+endif::git-asciidoc-no-roff[]
+endif::backend-docbook[]
+
+ifdef::doctype-manpage[]
+ifdef::backend-docbook[]
+[header]
+template::[header-declarations]
+<refentry>
+<refmeta>
+<refentrytitle>{mantitle}</refentrytitle>
+<manvolnum>{manvolnum}</manvolnum>
+<refmiscinfo class="source">Git</refmiscinfo>
+<refmiscinfo class="version">{git_version}</refmiscinfo>
+<refmiscinfo class="manual">Git Manual</refmiscinfo>
+</refmeta>
+<refnamediv>
+  <refname>{manname}</refname>
+  <refpurpose>{manpurpose}</refpurpose>
+</refnamediv>
+endif::backend-docbook[]
+endif::doctype-manpage[]
+
+ifdef::backend-xhtml11[]
+[linkgit-inlinemacro]
+<a href="{target}.html">{target}{0?({0})}</a>
+endif::backend-xhtml11[]

git-subtree.txt

@@ -0,0 +1,233 @@
+git-subtree(1)
+==============
+
+NAME
+----
+git-subtree - add, merge, and split subprojects stored in subtrees
+
+
+SYNOPSIS
+--------
+[verse]
+'git subtree' add   --prefix=<prefix> <commit>
+'git subtree' merge --prefix=<prefix> <commit>
+'git subtree' pull  --prefix=<prefix> <repository> <refspec...>
+'git subtree' split --prefix=<prefix> <commit...>
+         
+
+DESCRIPTION
+-----------
+git subtree allows you to include an subproject in your
+own repository as a subdirectory, optionally including the
+subproject's entire history. For example, you could
+include the source code for a library as a subdirectory of your
+application.
+
+You can also extract the entire history of a subdirectory from
+your project and make it into a standalone project.  For
+example, if a library you made for one application ends up being
+useful elsewhere, you can extract its entire history and publish
+that as its own git repository, without accidentally
+intermingling the history of your application project.
+
+Most importantly, you can alternate back and forth between these
+two operations.  If the standalone library gets updated, you can
+automatically merge the changes into your project; if you
+update the library inside your project, you can "split" the
+changes back out again and merge them back into the library
+project.
+
+Unlike the 'git submodule' command, git subtree doesn't produce
+any special constructions (like .gitmodule files or gitlinks) in
+your repository, and doesn't require end-users of your
+repository to do anything special or to understand how subtrees
+work.  A subtree is just another subdirectory and can be
+committed to, branched, and merged along with your project in
+any way you want.
+
+In order to keep your commit messages clean, we recommend that
+people split their commits between the subtrees and the main
+project as much as possible.  That is, if you make a change that
+affects both the library and the main application, commit it in
+two pieces.  That way, when you split the library commits out
+later, their descriptions will still make sense.  But if this
+isn't important to you, it's not *necessary*.  git subtree will
+simply leave out the non-library-related parts of the commit
+when it splits it out into the subproject later.
+
+
+COMMANDS
+--------
+add::
+	Create the <prefix> subtree by importing its contents
+	from the given commit.  A new commit is created
+	automatically, joining the imported project's history
+	with your own.  With '--squash', imports only a single
+	commit from the subproject, rather than its entire
+	history.
+
+merge::
+	Merge recent changes up to <commit> into the <prefix>
+	subtree.  As with normal 'git merge', this doesn't
+	remove your own local changes; it just merges those
+	changes into the latest <commit>.  With '--squash',
+	creates only one commit that contains all the changes,
+	rather than merging in the entire history.
+
+	If you use '--squash', the merge direction doesn't
+	always have to be forward; you can use this command to
+	go back in time from v2.5 to v2.4, for example.  If your
+	merge introduces a conflict, you can resolve it in the
+	usual ways.
+	
+pull::
+	Exactly like 'merge', but parallels 'git pull' in that
+	it fetches the given commit from the specified remote
+	repository.
+
+split::
+	Extract a new, synthetic project history from the
+	history of the <prefix> subtree.  The new history
+	includes only the commits (including merges) that
+	affected <prefix>, and each of those commits now has the
+	contents of <prefix> at the root of the project instead
+	of in a subdirectory.  Thus, the newly created history
+	is suitable for export as a separate git repository.
+	
+	After splitting successfully, a single commit id is
+	printed to stdout.  This corresponds to the HEAD of the
+	newly created tree, which you can manipulate however you
+	want.
+	
+	Repeated splits of exactly the same history are
+	guaranteed to be identical (ie. to produce the same
+	commit ids).  Because of this, if you add new commits
+	and then re-split, the new commits will be attached as
+	commits on top of the history you generated last time,
+	so 'git merge' and friends will work as expected.
+	
+	Note that if you use '--squash' when you merge, you
+	should usually not just '--rejoin' when you split.
+
+
+OPTIONS
+-------
+-q::
+--quiet::
+	Suppress unnecessary output messages on stderr.
+
+-d::
+--debug::
+	Produce even more unnecessary output messages on stderr.
+
+--prefix=<prefix>::
+	Specify the path in the repository to the subtree you
+	want to manipulate.  This option is currently mandatory
+	for all commands.
+
+
+OPTIONS FOR add, merge, AND pull
+--------------------------------
+--squash::
+	Instead of merging the entire history from the subtree
+	project, produce only a single commit that contains all
+	the differences you want to merge, and then merge that
+	new commit into your project.
+
+	Using this option helps to reduce log clutter. People
+	rarely want to see every change that happened between
+	v1.0 and v1.1 of the library they're using, since none of the
+	interim versions were ever included in their application.
+	
+	Using '--squash' also helps avoid problems when the same
+	subproject is included multiple times in the same
+	project, or is removed and then re-added.  In such a
+	case, it doesn't make sense to combine the histories
+	anyway, since it's unclear which part of the history
+	belongs to which subtree.
+	
+	Furthermore, with '--squash', you can switch back and
+	forth between different versions of a subtree, rather
+	than strictly forward.  'git subtree merge --squash'
+	always adjusts the subtree to match the exactly
+	specified commit, even if getting to that commit would
+	require undoing some changes that were added earlier.
+	
+	Whether or not you use '--squash', changes made in your
+	local repository remain intact and can be later split
+	and send upstream to the subproject.
+
+
+OPTIONS FOR split
+-----------------
+--annotate=<annotation>::
+	When generating synthetic history, add <annotation> as a
+	prefix to each commit message.  Since we're creating new
+	commits with the same commit message, but possibly
+	different content, from the original commits, this can help
+	to differentiate them and avoid confusion.
+	
+	Whenever you split, you need to use the same
+	<annotation>, or else you don't have a guarantee that
+	the new re-created history will be identical to the old
+	one.  That will prevent merging from working correctly. 
+	git subtree tries to make it work anyway, particularly
+	if you use --rejoin, but it may not always be effective.
+
+-b <branch>::
+--branch=<branch>::
+	After generating the synthetic history, create a new
+	branch called <branch> that contains the new history. 
+	This is suitable for immediate pushing upstream. 
+	<branch> must not already exist.
+
+--ignore-joins::
+	If you use '--rejoin', git subtree attempts to optimize
+	its history reconstruction to generate only the new
+	commits since the last '--rejoin'.  '--ignore-join'
+	disables this behaviour, forcing it to regenerate the
+	entire history.  In a large project, this can take a
+	long time.
+
+--onto=<onto>::
+	If your subtree was originally imported using something
+	other than git subtree, its history may not match what
+	git subtree is expecting.  In that case, you can specify
+	the commit id <onto> that corresponds to the first
+	revision of the subproject's history that was imported
+	into your project, and git subtree will attempt to build
+	its history from there.
+	
+	If you used 'git subtree add', you should never need
+	this option.
+
+--rejoin::
+	After splitting, merge the newly created synthetic
+	history back into your main project.  That way, future
+	splits can search only the part of history that has
+	been added since the most recent --rejoin.
+	
+	If your split commits end up merged into the upstream
+	subproject, and then you want to get the latest upstream
+	version, this will allow git's merge algorithm to more
+	intelligently avoid conflicts (since it knows these
+	synthetic commits are already part of the upstream
+	repository).
+	
+	Unfortunately, using this option results in 'git log'
+	showing an extra copy of every new commit that was
+	created (the original, and the synthetic one).
+	
+	If you do all your merges with '--squash', don't use
+	'--rejoin' when you split, because you don't want the
+	subproject's history to be part of your project anyway.
+
+
+AUTHOR
+------
+Written by Avery Pennarun <apenwarr@gmail.com>
+
+
+GIT
+---
+Part of the linkgit:git[1] suite

manpage-base.xsl

@@ -0,0 +1,35 @@
+<!-- manpage-base.xsl:
+     special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<!-- these params silence some output from xmlto -->
+<xsl:param name="man.output.quietly" select="1"/>
+<xsl:param name="refentry.meta.get.quietly" select="1"/>
+
+<!-- convert asciidoc callouts to man page format;
+     git.docbook.backslash and git.docbook.dot params
+     must be supplied by another XSL file or other means -->
+<xsl:template match="co">
+	<xsl:value-of select="concat(
+			      $git.docbook.backslash,'fB(',
+			      substring-after(@id,'-'),')',
+			      $git.docbook.backslash,'fR')"/>
+</xsl:template>
+<xsl:template match="calloutlist">
+	<xsl:value-of select="$git.docbook.dot"/>
+	<xsl:text>sp&#10;</xsl:text>
+	<xsl:apply-templates/>
+	<xsl:text>&#10;</xsl:text>
+</xsl:template>
+<xsl:template match="callout">
+	<xsl:value-of select="concat(
+			      $git.docbook.backslash,'fB',
+			      substring-after(@arearefs,'-'),
+			      '. ',$git.docbook.backslash,'fR')"/>
+	<xsl:apply-templates/>
+	<xsl:value-of select="$git.docbook.dot"/>
+	<xsl:text>br&#10;</xsl:text>
+</xsl:template>
+
+</xsl:stylesheet>

manpage-normal.xsl

@@ -0,0 +1,13 @@
+<!-- manpage-normal.xsl:
+     special settings for manpages rendered from asciidoc+docbook
+     handles anything we want to keep away from docbook-xsl 1.72.0 -->
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+		version="1.0">
+
+<xsl:import href="manpage-base.xsl"/>
+
+<!-- these are the normal values for the roff control characters -->
+<xsl:param name="git.docbook.backslash">\</xsl:param>
+<xsl:param name="git.docbook.dot"	>.</xsl:param>
+
+</xsl:stylesheet>