Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Add basic git-subtree manpage in asciidoc format.

  • Loading branch information...
commit e75d1da38a7091c15ebd3c80539e4aab20faf5b7 1 parent d713e2d
apenwarr authored
2  .gitignore
... ... @@ -1 +1,3 @@
1 1 *~
  2 +git-subtree.xml
  3 +git-subtree.1
18 Makefile
... ... @@ -0,0 +1,18 @@
  1 +default:
  2 + @echo "git-subtree doesn't need to be built."
  3 + @echo
  4 + @echo "Try: make doc"
  5 + @false
  6 +
  7 +doc: git-subtree.1
  8 +
  9 +%.1: %.xml
  10 + xmlto -m manpage-normal.xsl man $^
  11 +
  12 +%.xml: %.txt
  13 + asciidoc -b docbook -d manpage -f asciidoc.conf \
  14 + -agit_version=1.6.3 $^
  15 +
  16 +clean:
  17 + rm -f *~ *.xml *.html *.1
  18 + rm -rf subproj mainline
91 asciidoc.conf
... ... @@ -0,0 +1,91 @@
  1 +## linkgit: macro
  2 +#
  3 +# Usage: linkgit:command[manpage-section]
  4 +#
  5 +# Note, {0} is the manpage section, while {target} is the command.
  6 +#
  7 +# Show GIT link as: <command>(<section>); if section is defined, else just show
  8 +# the command.
  9 +
  10 +[macros]
  11 +(?su)[\\]?(?P<name>linkgit):(?P<target>\S*?)\[(?P<attrlist>.*?)\]=
  12 +
  13 +[attributes]
  14 +asterisk=&#42;
  15 +plus=&#43;
  16 +caret=&#94;
  17 +startsb=&#91;
  18 +endsb=&#93;
  19 +tilde=&#126;
  20 +
  21 +ifdef::backend-docbook[]
  22 +[linkgit-inlinemacro]
  23 +{0%{target}}
  24 +{0#<citerefentry>}
  25 +{0#<refentrytitle>{target}</refentrytitle><manvolnum>{0}</manvolnum>}
  26 +{0#</citerefentry>}
  27 +endif::backend-docbook[]
  28 +
  29 +ifdef::backend-docbook[]
  30 +ifndef::git-asciidoc-no-roff[]
  31 +# "unbreak" docbook-xsl v1.68 for manpages. v1.69 works with or without this.
  32 +# v1.72 breaks with this because it replaces dots not in roff requests.
  33 +[listingblock]
  34 +<example><title>{title}</title>
  35 +<literallayout>
  36 +ifdef::doctype-manpage[]
  37 +&#10;.ft C&#10;
  38 +endif::doctype-manpage[]
  39 +|
  40 +ifdef::doctype-manpage[]
  41 +&#10;.ft&#10;
  42 +endif::doctype-manpage[]
  43 +</literallayout>
  44 +{title#}</example>
  45 +endif::git-asciidoc-no-roff[]
  46 +
  47 +ifdef::git-asciidoc-no-roff[]
  48 +ifdef::doctype-manpage[]
  49 +# The following two small workarounds insert a simple paragraph after screen
  50 +[listingblock]
  51 +<example><title>{title}</title>
  52 +<literallayout>
  53 +|
  54 +</literallayout><simpara></simpara>
  55 +{title#}</example>
  56 +
  57 +[verseblock]
  58 +<formalpara{id? id="{id}"}><title>{title}</title><para>
  59 +{title%}<literallayout{id? id="{id}"}>
  60 +{title#}<literallayout>
  61 +|
  62 +</literallayout>
  63 +{title#}</para></formalpara>
  64 +{title%}<simpara></simpara>
  65 +endif::doctype-manpage[]
  66 +endif::git-asciidoc-no-roff[]
  67 +endif::backend-docbook[]
  68 +
  69 +ifdef::doctype-manpage[]
  70 +ifdef::backend-docbook[]
  71 +[header]
  72 +template::[header-declarations]
  73 +<refentry>
  74 +<refmeta>
  75 +<refentrytitle>{mantitle}</refentrytitle>
  76 +<manvolnum>{manvolnum}</manvolnum>
  77 +<refmiscinfo class="source">Git</refmiscinfo>
  78 +<refmiscinfo class="version">{git_version}</refmiscinfo>
  79 +<refmiscinfo class="manual">Git Manual</refmiscinfo>
  80 +</refmeta>
  81 +<refnamediv>
  82 + <refname>{manname}</refname>
  83 + <refpurpose>{manpurpose}</refpurpose>
  84 +</refnamediv>
  85 +endif::backend-docbook[]
  86 +endif::doctype-manpage[]
  87 +
  88 +ifdef::backend-xhtml11[]
  89 +[linkgit-inlinemacro]
  90 +<a href="{target}.html">{target}{0?({0})}</a>
  91 +endif::backend-xhtml11[]
233 git-subtree.txt
... ... @@ -0,0 +1,233 @@
  1 +git-subtree(1)
  2 +==============
  3 +
  4 +NAME
  5 +----
  6 +git-subtree - add, merge, and split subprojects stored in subtrees
  7 +
  8 +
  9 +SYNOPSIS
  10 +--------
  11 +[verse]
  12 +'git subtree' add --prefix=<prefix> <commit>
  13 +'git subtree' merge --prefix=<prefix> <commit>
  14 +'git subtree' pull --prefix=<prefix> <repository> <refspec...>
  15 +'git subtree' split --prefix=<prefix> <commit...>
  16 +
  17 +
  18 +DESCRIPTION
  19 +-----------
  20 +git subtree allows you to include an subproject in your
  21 +own repository as a subdirectory, optionally including the
  22 +subproject's entire history. For example, you could
  23 +include the source code for a library as a subdirectory of your
  24 +application.
  25 +
  26 +You can also extract the entire history of a subdirectory from
  27 +your project and make it into a standalone project. For
  28 +example, if a library you made for one application ends up being
  29 +useful elsewhere, you can extract its entire history and publish
  30 +that as its own git repository, without accidentally
  31 +intermingling the history of your application project.
  32 +
  33 +Most importantly, you can alternate back and forth between these
  34 +two operations. If the standalone library gets updated, you can
  35 +automatically merge the changes into your project; if you
  36 +update the library inside your project, you can "split" the
  37 +changes back out again and merge them back into the library
  38 +project.
  39 +
  40 +Unlike the 'git submodule' command, git subtree doesn't produce
  41 +any special constructions (like .gitmodule files or gitlinks) in
  42 +your repository, and doesn't require end-users of your
  43 +repository to do anything special or to understand how subtrees
  44 +work. A subtree is just another subdirectory and can be
  45 +committed to, branched, and merged along with your project in
  46 +any way you want.
  47 +
  48 +In order to keep your commit messages clean, we recommend that
  49 +people split their commits between the subtrees and the main
  50 +project as much as possible. That is, if you make a change that
  51 +affects both the library and the main application, commit it in
  52 +two pieces. That way, when you split the library commits out
  53 +later, their descriptions will still make sense. But if this
  54 +isn't important to you, it's not *necessary*. git subtree will
  55 +simply leave out the non-library-related parts of the commit
  56 +when it splits it out into the subproject later.
  57 +
  58 +
  59 +COMMANDS
  60 +--------
  61 +add::
  62 + Create the <prefix> subtree by importing its contents
  63 + from the given commit. A new commit is created
  64 + automatically, joining the imported project's history
  65 + with your own. With '--squash', imports only a single
  66 + commit from the subproject, rather than its entire
  67 + history.
  68 +
  69 +merge::
  70 + Merge recent changes up to <commit> into the <prefix>
  71 + subtree. As with normal 'git merge', this doesn't
  72 + remove your own local changes; it just merges those
  73 + changes into the latest <commit>. With '--squash',
  74 + creates only one commit that contains all the changes,
  75 + rather than merging in the entire history.
  76 +
  77 + If you use '--squash', the merge direction doesn't
  78 + always have to be forward; you can use this command to
  79 + go back in time from v2.5 to v2.4, for example. If your
  80 + merge introduces a conflict, you can resolve it in the
  81 + usual ways.
  82 +
  83 +pull::
  84 + Exactly like 'merge', but parallels 'git pull' in that
  85 + it fetches the given commit from the specified remote
  86 + repository.
  87 +
  88 +split::
  89 + Extract a new, synthetic project history from the
  90 + history of the <prefix> subtree. The new history
  91 + includes only the commits (including merges) that
  92 + affected <prefix>, and each of those commits now has the
  93 + contents of <prefix> at the root of the project instead
  94 + of in a subdirectory. Thus, the newly created history
  95 + is suitable for export as a separate git repository.
  96 +
  97 + After splitting successfully, a single commit id is
  98 + printed to stdout. This corresponds to the HEAD of the
  99 + newly created tree, which you can manipulate however you
  100 + want.
  101 +
  102 + Repeated splits of exactly the same history are
  103 + guaranteed to be identical (ie. to produce the same
  104 + commit ids). Because of this, if you add new commits
  105 + and then re-split, the new commits will be attached as
  106 + commits on top of the history you generated last time,
  107 + so 'git merge' and friends will work as expected.
  108 +
  109 + Note that if you use '--squash' when you merge, you
  110 + should usually not just '--rejoin' when you split.
  111 +
  112 +
  113 +OPTIONS
  114 +-------
  115 +-q::
  116 +--quiet::
  117 + Suppress unnecessary output messages on stderr.
  118 +
  119 +-d::
  120 +--debug::
  121 + Produce even more unnecessary output messages on stderr.
  122 +
  123 +--prefix=<prefix>::
  124 + Specify the path in the repository to the subtree you
  125 + want to manipulate. This option is currently mandatory
  126 + for all commands.
  127 +
  128 +
  129 +OPTIONS FOR add, merge, AND pull
  130 +--------------------------------
  131 +--squash::
  132 + Instead of merging the entire history from the subtree
  133 + project, produce only a single commit that contains all
  134 + the differences you want to merge, and then merge that
  135 + new commit into your project.
  136 +
  137 + Using this option helps to reduce log clutter. People
  138 + rarely want to see every change that happened between
  139 + v1.0 and v1.1 of the library they're using, since none of the
  140 + interim versions were ever included in their application.
  141 +
  142 + Using '--squash' also helps avoid problems when the same
  143 + subproject is included multiple times in the same
  144 + project, or is removed and then re-added. In such a
  145 + case, it doesn't make sense to combine the histories
  146 + anyway, since it's unclear which part of the history
  147 + belongs to which subtree.
  148 +
  149 + Furthermore, with '--squash', you can switch back and
  150 + forth between different versions of a subtree, rather
  151 + than strictly forward. 'git subtree merge --squash'
  152 + always adjusts the subtree to match the exactly
  153 + specified commit, even if getting to that commit would
  154 + require undoing some changes that were added earlier.
  155 +
  156 + Whether or not you use '--squash', changes made in your
  157 + local repository remain intact and can be later split
  158 + and send upstream to the subproject.
  159 +
  160 +
  161 +OPTIONS FOR split
  162 +-----------------
  163 +--annotate=<annotation>::
  164 + When generating synthetic history, add <annotation> as a
  165 + prefix to each commit message. Since we're creating new
  166 + commits with the same commit message, but possibly
  167 + different content, from the original commits, this can help
  168 + to differentiate them and avoid confusion.
  169 +
  170 + Whenever you split, you need to use the same
  171 + <annotation>, or else you don't have a guarantee that
  172 + the new re-created history will be identical to the old
  173 + one. That will prevent merging from working correctly.
  174 + git subtree tries to make it work anyway, particularly
  175 + if you use --rejoin, but it may not always be effective.
  176 +
  177 +-b <branch>::
  178 +--branch=<branch>::
  179 + After generating the synthetic history, create a new
  180 + branch called <branch> that contains the new history.
  181 + This is suitable for immediate pushing upstream.
  182 + <branch> must not already exist.
  183 +
  184 +--ignore-joins::
  185 + If you use '--rejoin', git subtree attempts to optimize
  186 + its history reconstruction to generate only the new
  187 + commits since the last '--rejoin'. '--ignore-join'
  188 + disables this behaviour, forcing it to regenerate the
  189 + entire history. In a large project, this can take a
  190 + long time.
  191 +
  192 +--onto=<onto>::
  193 + If your subtree was originally imported using something
  194 + other than git subtree, its history may not match what
  195 + git subtree is expecting. In that case, you can specify
  196 + the commit id <onto> that corresponds to the first
  197 + revision of the subproject's history that was imported
  198 + into your project, and git subtree will attempt to build
  199 + its history from there.
  200 +
  201 + If you used 'git subtree add', you should never need
  202 + this option.
  203 +
  204 +--rejoin::
  205 + After splitting, merge the newly created synthetic
  206 + history back into your main project. That way, future
  207 + splits can search only the part of history that has
  208 + been added since the most recent --rejoin.
  209 +
  210 + If your split commits end up merged into the upstream
  211 + subproject, and then you want to get the latest upstream
  212 + version, this will allow git's merge algorithm to more
  213 + intelligently avoid conflicts (since it knows these
  214 + synthetic commits are already part of the upstream
  215 + repository).
  216 +
  217 + Unfortunately, using this option results in 'git log'
  218 + showing an extra copy of every new commit that was
  219 + created (the original, and the synthetic one).
  220 +
  221 + If you do all your merges with '--squash', don't use
  222 + '--rejoin' when you split, because you don't want the
  223 + subproject's history to be part of your project anyway.
  224 +
  225 +
  226 +AUTHOR
  227 +------
  228 +Written by Avery Pennarun <apenwarr@gmail.com>
  229 +
  230 +
  231 +GIT
  232 +---
  233 +Part of the linkgit:git[1] suite
35 manpage-base.xsl
... ... @@ -0,0 +1,35 @@
  1 +<!-- manpage-base.xsl:
  2 + special formatting for manpages rendered from asciidoc+docbook -->
  3 +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  4 + version="1.0">
  5 +
  6 +<!-- these params silence some output from xmlto -->
  7 +<xsl:param name="man.output.quietly" select="1"/>
  8 +<xsl:param name="refentry.meta.get.quietly" select="1"/>
  9 +
  10 +<!-- convert asciidoc callouts to man page format;
  11 + git.docbook.backslash and git.docbook.dot params
  12 + must be supplied by another XSL file or other means -->
  13 +<xsl:template match="co">
  14 + <xsl:value-of select="concat(
  15 + $git.docbook.backslash,'fB(',
  16 + substring-after(@id,'-'),')',
  17 + $git.docbook.backslash,'fR')"/>
  18 +</xsl:template>
  19 +<xsl:template match="calloutlist">
  20 + <xsl:value-of select="$git.docbook.dot"/>
  21 + <xsl:text>sp&#10;</xsl:text>
  22 + <xsl:apply-templates/>
  23 + <xsl:text>&#10;</xsl:text>
  24 +</xsl:template>
  25 +<xsl:template match="callout">
  26 + <xsl:value-of select="concat(
  27 + $git.docbook.backslash,'fB',
  28 + substring-after(@arearefs,'-'),
  29 + '. ',$git.docbook.backslash,'fR')"/>
  30 + <xsl:apply-templates/>
  31 + <xsl:value-of select="$git.docbook.dot"/>
  32 + <xsl:text>br&#10;</xsl:text>
  33 +</xsl:template>
  34 +
  35 +</xsl:stylesheet>
13 manpage-normal.xsl
... ... @@ -0,0 +1,13 @@
  1 +<!-- manpage-normal.xsl:
  2 + special settings for manpages rendered from asciidoc+docbook
  3 + handles anything we want to keep away from docbook-xsl 1.72.0 -->
  4 +<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  5 + version="1.0">
  6 +
  7 +<xsl:import href="manpage-base.xsl"/>
  8 +
  9 +<!-- these are the normal values for the roff control characters -->
  10 +<xsl:param name="git.docbook.backslash">\</xsl:param>
  11 +<xsl:param name="git.docbook.dot" >.</xsl:param>
  12 +
  13 +</xsl:stylesheet>

0 comments on commit e75d1da

John Yani

Hi. I'm a little confused with "an" article before consonant (subproject). English is not my native language, so could you explain this to me, please? Maybe this is a typo?

Markus Prinz

The rule is pretty simple: If the word after "a" starts with a vowel, you must use "an" ("an egg" vs. "a cup"). So in this case, this is a typo.

apenwarr

Fixed, thanks.

Bryan Larsen

To be pedantic, the rule isn't quite that simple. Silent letters usually (but not always) are ignored. For instance: "an honour" would be the correct usage as long as the British spelling doesn't bother you. :)

In this case, it was just a typo. :)

John Yani

Ok, thanks. I've already fixed it locally before I saw these comments. BTW, I've made some changes to docs, have a look, please.

Please sign in to comment.
Something went wrong with that request. Please try again.