Shourya Shukla <shouryashukla.oo@xxxxxxxxx> writes:
> Add more issues and their respective solutions in the 'Common Issues'
> section of gitfaq.
It probably would have been much easier to discuss if these sections
were separate patches.
Also, each physical line is way too long to view without line
wrapping (even on my wider-than-usual 92 col terminal). Please wrap
lines at a more reasonable column, like 65-72.
> +[[rebasing-and-merging]]
> +How do I know when to merge or rebase?::
> + Rebasing and merging two entirely different concepts with different utiilites.
> + In Git terms, rebasing means to place changes made in one branch over another branch
> + (called base, hence the term, rebase). The commit history of the branch wanting to rebase
> + get placed over the branch on the receiving end and it appears as if those changes took
> + place in the receiving branch itself.
"the branch wanting to rebase"? Did you mean "the branc being
rebased"? Except for that the above looks quite reasonable.
> + Merging, as the name suggests, merges the latest
> + commit of one branch onto the recent branch, making this combination appear as one separate
> + commit.
This description is a bit iffy. There is nothing special about "the
latest commit" among the commits on the branch being merged---if you
had a two-commit side branch and you merged that branch to another
branch, the changes made by _both_ commits would appear in the
result; I don't find much value in saying "the latest commit of one
branch" (besides, merging an early part of a branch alone, while
leaving more later parts of the branch still not merged, is a valid
thing to do).
Merging binds two (or more) lines of histories into one history,
reflecting what these branches wanted to do to the files since
they forked from their common ancestor and recording the result
as one new "merge" commit that is a direct descendant of the
tips of these branches.
perhaps.
[jc: it is impossible to comment on the overlong lines, so I'd
remove the '+'(added) sign and reflow the paragraphs]
> Now that we have an idea of the key differences between merging
> and rebasing, we can look at the circumstances when we would want
> to perform them.
OK.
> Generally, merging is preferred when one desires
> to create a new feature, perform its integration testing with the
> original codebase, and finally integrate it if all tests are
> passed.
This is an unsubstantiated claim (opinion) and I do not know if I
agree with it.
I do not think we want to have such a sentence as if it were our
official recommendation in our documentation set---it is OK to write
such things on your blog, but not here.
> One would choose to create a separate branch for this purpose and
> maybe dissolve it when the merge is done.
It is unclear what you mean by "dissolve" here. Do you mean "build
a new feature on a topic branch, use the branch to polish the feature
until it is perfect, and merge it to the trunk, at which point, the
topic branch is no longer needed so it can be discarded"?
> One might want to perform a rebase when they intend to retain the
> changes made in a separate branch into their original branch.
This reads as if you are describing: "I want to keep the original,
but I want to use the same changes elsewhere" but I do not think it
is a good match for "rebase" in the first place. It sounds more
like you are talking about cherry-picking.
And "merge" is also perfectly fine way to do so, as long as the
original development was done based on the right commit. If you
originally based your fix on a commit that is too new in the
history, even though the problem you wanted to fix appeared much
earlier in the history, you obviously cannot fix the problem for an
older maintenance track by merging, and at that point, you may
either
(1) cherry-pick (i.e. duplicate) the fixes to older maintenance
track, while keeping the fixes based on a newer codebase; or
(2) rebase the fixes, that were originally done on a newer
codebase, to the oldest maintenance track that still matters,
and then discard the original fixes and instead merge the
result of rebasing to the newer codebase.
If you can afford to do (2), it is _always_ preferrable to do so,
but often you cannot and you end up doing (1).
Notice that the preferred workflow has *both* rebasing and merging
as crucial elements. It's not like "when to do rebase, and when to
merge" as you set out this section to be. It is often more like
"you rebase, in preparation to merge".
> In that case, a rebase would place the former changes onto the
> commit tree of the latter.
> As an additional tip, one can use interactive rebasing, `git
> rebase -i`, to perform rebasing using a text editor GUI (the value
> of $GIT_EDITOR). Interactive rebase is an excellent utility to
> perform various functions such as editing commit messages,
> dropping/squashing commits, editing commits, etc., all in one
> package.
I think what the description is lacking *most* is *why* and without
that it would not be as useful as it could be to the readers. Why
does one want to rebase commits on a branch? When the reader knows
the answer to that question clearly, various things "rebase" lets
its users do would make sense.
In the context of "I now have my first iteration of a topic (be it a
feature or a fix)", one would perform rebase because of different
reasons (and they are not exclusive):
- Your first attempt may have been built on a wrong commit, so you
want to restart your topic branch at a different "base".
. You may have written a helper function in your code yourself,
because you started your topic branch at the latest release
tag, but later you may have noticed that the same helper
function is already available for your use in the current
development version. By restarting your topic branch at a
later commit, you do not have to reinvent the helper function
yourself, hence you may want to rebase your topic at the tip of
the current development version.
. You may have developed a fix on top of the latest release tag,
but then realized that the bug you fixed was already there in
the previous release. You obviously cannot merge your fix
directly to the previous release, because doing so would also
pull down all the changes in the latest release. By restarting
your topic branch with your fix at the previous release point,
you can apply the fix (and no other changes that the latest
release has) to the earlier codebase. And if your newer
codebase is a superset of your older codebase, you can fix the
same bug in the newer codebase by simply merging the fix to the
newer codebase (and your original topic branch based on the
latest release tag is no longer needed, so you can discard it).
- Your commits may have unnecessary or wrong code, or log message,
or both. They may be in a wrong order. You would rebuild your
history, either on the same base or a different one, and tweak
each commit as you do so.
And "rebase -i" was invented exactly for that purpose.
I won't comment on the other sections in this message (I may do so
in separate ones).
Thanks.
