From e75d1da38a7091c15ebd3c80539e4aab20faf5b7 Mon Sep 17 00:00:00 2001 From: Avery Pennarun Date: Sat, 30 May 2009 14:05:33 -0400 Subject: [PATCH] Add basic git-subtree manpage in asciidoc format. --- .gitignore | 2 + Makefile | 18 ++++ asciidoc.conf | 91 ++++++++++++++++++ git-subtree.txt | 233 +++++++++++++++++++++++++++++++++++++++++++++ manpage-base.xsl | 35 +++++++ manpage-normal.xsl | 13 +++ 6 files changed, 392 insertions(+) create mode 100644 Makefile create mode 100644 asciidoc.conf create mode 100644 git-subtree.txt create mode 100644 manpage-base.xsl create mode 100644 manpage-normal.xsl diff --git a/.gitignore b/.gitignore index b25c15b81f..e358b18b78 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,3 @@ *~ +git-subtree.xml +git-subtree.1 diff --git a/Makefile b/Makefile new file mode 100644 index 0000000000..bc163dd390 --- /dev/null +++ b/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 diff --git a/asciidoc.conf b/asciidoc.conf new file mode 100644 index 0000000000..dc76e7f073 --- /dev/null +++ b/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: (
); if section is defined, else just show +# the command. + +[macros] +(?su)[\\]?(?Plinkgit):(?P\S*?)\[(?P.*?)\]= + +[attributes] +asterisk=* +plus=+ +caret=^ +startsb=[ +endsb=] +tilde=~ + +ifdef::backend-docbook[] +[linkgit-inlinemacro] +{0%{target}} +{0#} +{0#{target}{0}} +{0#} +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] +{title} + +ifdef::doctype-manpage[] + .ft C +endif::doctype-manpage[] +| +ifdef::doctype-manpage[] + .ft +endif::doctype-manpage[] + +{title#} +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] +{title} + +| + +{title#} + +[verseblock] +{title} +{title%} +{title#} +| + +{title#} +{title%} +endif::doctype-manpage[] +endif::git-asciidoc-no-roff[] +endif::backend-docbook[] + +ifdef::doctype-manpage[] +ifdef::backend-docbook[] +[header] +template::[header-declarations] + + +{mantitle} +{manvolnum} +Git +{git_version} +Git Manual + + + {manname} + {manpurpose} + +endif::backend-docbook[] +endif::doctype-manpage[] + +ifdef::backend-xhtml11[] +[linkgit-inlinemacro] +{target}{0?({0})} +endif::backend-xhtml11[] diff --git a/git-subtree.txt b/git-subtree.txt new file mode 100644 index 0000000000..d10630180d --- /dev/null +++ b/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= +'git subtree' merge --prefix= +'git subtree' pull --prefix= +'git subtree' split --prefix= + + +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 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 into the + subtree. As with normal 'git merge', this doesn't + remove your own local changes; it just merges those + changes into the latest . 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 subtree. The new history + includes only the commits (including merges) that + affected , and each of those commits now has the + contents of 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=:: + 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=:: + When generating synthetic history, add 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 + , 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 that contains the new history. + This is suitable for immediate pushing upstream. + 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=:: + 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 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 + + +GIT +--- +Part of the linkgit:git[1] suite diff --git a/manpage-base.xsl b/manpage-base.xsl new file mode 100644 index 0000000000..a264fa6160 --- /dev/null +++ b/manpage-base.xsl @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + sp + + + + + + + + br + + + diff --git a/manpage-normal.xsl b/manpage-normal.xsl new file mode 100644 index 0000000000..a48f5b11f3 --- /dev/null +++ b/manpage-normal.xsl @@ -0,0 +1,13 @@ + + + + + + +\ +. + + -- 2.43.2