On Saturday 2008 December 20 20:36:43 Junio C Hamano wrote: > "Boyd Stephen Smith Jr." <bss@xxxxxxxxxxxxxxxxx> writes: > > --- > > An example addition to the manpage for revert that references Nanako > > Shiraishi's new documentation. > > > > Documentation/git-revert.txt | 4 ++++ > > 1 files changed, 4 insertions(+), 0 deletions(-) > > > > diff --git a/Documentation/git-revert.txt b/Documentation/git-revert.txt > > index caa0729..ea36bdf 100644 > > --- a/Documentation/git-revert.txt > > +++ b/Documentation/git-revert.txt > > @@ -45,6 +45,10 @@ OPTIONS > > the mainline and allows revert to reverse the change > > relative to the specified parent. > > > > + Reverting a merge commit does not completely "undo" the effect of the > > + merge and it may make future merges more difficult. For more details, > > + please read Documentation/howto/revert-a-faulty-merge.txt. > > + > > I think these new lines need to be dedented, and the previous blank line > should be turned into a line with a single '+'. Can do. > I'd also suggest removing "does not ... merge and it" from the above > sentence to avoid confusing readers, because people who read only the > above and do not read the howto document may get a wrong impression that > the resulting tree may have some changes that came from the merge even > after the revert, which is not the case. Revert will erase the effect the > merge had to your tree and that part is complete. But that is not the whole effect of the merge. The effect of the merge is both the modifications it makes to the tree and the modifications it makes to the history. Going from the dictionary meaning for "revert", one might expect the those effects to go away as well. I think a warning that the revert subcommand does not fully revert the merge is appropriate. > Linus's "does not completely undo" only refers to the history part of the > merge, and that only affects future re-merges from the same branch, which > the reader who is interested in doing a revert of a merge right now (that > is why s/he is reading this paragraph) may not yet care about. They may not care about it now, but it doesn't make much sense to warn about it during the later merge (plus it might be computationally expensive to detect). > An alternative is to give a complete but brief explanation. Perhaps like > this: > > By reverting a merge, you are declaring that you will never want the > changes that were brought in by that merge you are reverting in your > tree. If you do merge from the same branch again in the future after > it is updated, git remembers your declaration, and only the changes on > the branch that were made after the reverted merge will be brought in. > This may or may not be what you want. See 'revert-a-faulty-merge' > HOWTO for more details. I think the wording might need to be changed a little bit, but I do like the longer, more complete and clear explanation and I'll work on a patch that has one. -- Boyd Stephen Smith Jr. ,= ,-_-. =. bss@xxxxxxxxxxxxxxxxx ((_/)o o(\_)) ICQ: 514984 YM/AIM: DaTwinkDaddy `-'(. .)`-' http://iguanasuicide.net/ \_/
Attachment:
signature.asc
Description: This is a digitally signed message part.
