1f010d6bdf
We presently use the ".txt" extension for our AsciiDoc files. While not wrong, most editors do not associate this extension with AsciiDoc, meaning that contributors don't get automatic editor functionality that could be useful, such as syntax highlighting and prose linting. It is much more common to use the ".adoc" extension for AsciiDoc files, since this helps editors automatically detect files and also allows various forges to provide rich (HTML-like) rendering. Let's do that here, renaming all of the files and updating the includes where relevant. Adjust the various build scripts and makefiles to use the new extension as well. Note that this should not result in any user-visible changes to the documentation. Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> Signed-off-by: Junio C Hamano <gitster@pobox.com>
76 lines
3.0 KiB
Plaintext
76 lines
3.0 KiB
Plaintext
Date: Sat, 5 Jan 2008 20:17:40 -0500
|
|
From: Sean <seanlkml@sympatico.ca>
|
|
To: Miklos Vajna <vmiklos@frugalware.org>
|
|
Cc: git@vger.kernel.org
|
|
Subject: how to use git merge -s subtree?
|
|
Abstract: In this article, Sean demonstrates how one can use the subtree merge
|
|
strategy.
|
|
Content-type: text/asciidoc
|
|
Message-ID: <BAYC1-PASMTP12374B54BA370A1E1C6E78AE4E0@CEZ.ICE>
|
|
|
|
How to use the subtree merge strategy
|
|
=====================================
|
|
|
|
There are situations where you want to include content in your project
|
|
from an independently developed project. You can just pull from the
|
|
other project as long as there are no conflicting paths.
|
|
|
|
The problematic case is when there are conflicting files. Potential
|
|
candidates are Makefiles and other standard filenames. You could merge
|
|
these files but probably you do not want to. A better solution for this
|
|
problem can be to merge the project as its own subdirectory. This is not
|
|
supported by the 'recursive' merge strategy, so just pulling won't work.
|
|
|
|
What you want is the 'subtree' merge strategy, which helps you in such a
|
|
situation.
|
|
|
|
In this example, let's say you have the repository at `/path/to/B` (but
|
|
it can be a URL as well, if you want). You want to merge the 'master'
|
|
branch of that repository to the `dir-B` subdirectory in your current
|
|
branch.
|
|
|
|
Here is the command sequence you need:
|
|
|
|
----------------
|
|
$ git remote add -f Bproject /path/to/B <1>
|
|
$ git merge -s ours --no-commit --allow-unrelated-histories Bproject/master <2>
|
|
$ git read-tree --prefix=dir-B/ -u Bproject/master <3>
|
|
$ git commit -m "Merge B project as our subdirectory" <4>
|
|
|
|
$ git pull -s subtree Bproject master <5>
|
|
----------------
|
|
<1> name the other project "Bproject", and fetch.
|
|
<2> prepare for the later step to record the result as a merge.
|
|
<3> read "master" branch of Bproject to the subdirectory "dir-B".
|
|
<4> record the merge result.
|
|
<5> maintain the result with subsequent merges using "subtree"
|
|
|
|
The first four commands are used for the initial merge, while the last
|
|
one is to merge updates from 'B project'.
|
|
|
|
Comparing 'subtree' merge with submodules
|
|
-----------------------------------------
|
|
|
|
- The benefit of using subtree merge is that it requires less
|
|
administrative burden from the users of your repository. It works with
|
|
older (before Git v1.5.2) clients and you have the code right after
|
|
clone.
|
|
|
|
- However if you use submodules then you can choose not to transfer the
|
|
submodule objects. This may be a problem with the subtree merge.
|
|
|
|
- Also, in case you make changes to the other project, it is easier to
|
|
submit changes if you just use submodules.
|
|
|
|
Additional tips
|
|
---------------
|
|
|
|
- If you made changes to the other project in your repository, they may
|
|
want to merge from your project. This is possible using subtree -- it
|
|
can shift up the paths in your tree and then they can merge only the
|
|
relevant parts of your tree.
|
|
|
|
- Please note that if the other project merges from you, then it will
|
|
connect its history to yours, which can be something they don't want
|
|
to.
|