Browse files

Add basic git-subtree manpage in asciidoc format.

  • Loading branch information...
1 parent d713e2d commit e75d1da38a7091c15ebd3c80539e4aab20faf5b7 @apenwarr apenwarr committed May 30, 2009
Showing with 392 additions and 0 deletions.
  1. +2 −0 .gitignore
  2. +18 −0 Makefile
  3. +91 −0 asciidoc.conf
  4. +233 −0 git-subtree.txt
  5. +35 −0 manpage-base.xsl
  6. +13 −0 manpage-normal.xsl
@@ -1 +1,3 @@
@@ -0,0 +1,18 @@
+ @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 $^
+ rm -f *~ *.xml *.html *.1
+ rm -rf subproj mainline
@@ -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.
+# "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.
+&#10;.ft C&#10;
+# The following two small workarounds insert a simple paragraph after screen
+<formalpara{id? id="{id}"}><title>{title}</title><para>
+{title%}<literallayout{id? id="{id}"}>
+<refmiscinfo class="source">Git</refmiscinfo>
+<refmiscinfo class="version">{git_version}</refmiscinfo>
+<refmiscinfo class="manual">Git Manual</refmiscinfo>
+ <refname>{manname}</refname>
+ <refpurpose>{manpurpose}</refpurpose>
+<a href="{target}.html">{target}{0?({0})}</a>
@@ -0,0 +1,233 @@
+git-subtree - add, merge, and split subprojects stored in subtrees
+'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...>
+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
+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
+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.
+ 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 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.
+ Exactly like 'merge', but parallels 'git pull' in that
+ it fetches the given commit from the specified remote
+ repository.
+ 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.
+ Suppress unnecessary output messages on stderr.
+ Produce even more unnecessary output messages on stderr.
+ 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
+ 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.
+ 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>::
+ 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.
+ 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.
+ 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.
+ 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.
+Written by Avery Pennarun <>
+Part of the linkgit:git[1] suite
@@ -0,0 +1,35 @@
+<!-- manpage-base.xsl:
+ special formatting for manpages rendered from asciidoc+docbook -->
+<xsl:stylesheet xmlns:xsl=""
+ 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 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 match="calloutlist">
+ <xsl:value-of select="$"/>
+ <xsl:text>sp&#10;</xsl:text>
+ <xsl:apply-templates/>
+ <xsl:text>&#10;</xsl:text>
+<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="$"/>
+ <xsl:text>br&#10;</xsl:text>
@@ -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=""
+ 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="" >.</xsl:param>

0 comments on commit e75d1da

Please sign in to comment.