Home Explore Blog CI



git

3rd chunk of `contrib/subtree/git-subtree.adoc`
a0ed30edd0c896af3de7abcb21b224939c4c4e3a99f06b9c0000000100000f04
	want to manipulate.  This option is mandatory
	for all commands.

OPTIONS FOR 'add' AND 'merge' (ALSO: 'pull', 'split --rejoin', AND 'push --rejoin')
-----------------------------------------------------------------------------------
These options for 'add' and 'merge' may also be given to 'pull' (which
wraps 'merge'), 'split --rejoin' (which wraps either 'add' or 'merge'
as appropriate), and 'push --rejoin' (which wraps 'split --rejoin').

--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.

-m <message>::
--message=<message>::
	Specify <message> as the commit message for the merge commit.

OPTIONS FOR 'split' (ALSO: 'push')
----------------------------------
These options for 'split' may also be given to 'push' (which wraps
'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-joins' disables this behavior, 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

Title: Git Subtree Command Options
Summary
The git-subtree command provides various options to customize its behavior, including --squash to reduce log clutter, --message to specify commit messages, --annotate to add prefixes to commit messages, --branch to create new branches, and --rejoin to merge synthetic history back into the main project, among others.