Am 23.10.20 um 16:38 schrieb Junio C Hamano: > Johannes Sixt <j6t@xxxxxxxx> writes: > >>> - Apply the patch to both the index and the working tree (or >>> - merely check that it would apply cleanly to both if `--check` is >>> - in effect). Note that `--index` expects index entries and >>> - working tree copies for relevant paths to be identical (their >>> - contents and metadata such as file mode must match), and will >>> - raise an error if they are not, even if the patch would apply >>> - cleanly to both the index and the working tree in isolation. >>> + After making sure the paths the patch touches in the working >>> + tree have no modifications relative to their index entries, >>> + apply the patch both to the index entries and to the working >>> + tree files or see if it applies cleanly, when `--check` is in >>> + effect. >> >> I don't think that this is an improvement. The purpose of --index *is* >> to apply the patch to both index and worktree, and that should be >> mentioned first. The check that both are identical, is a prerequisite >> and not the primary objective of the option. > > Yeah, but this was an attempt to clarify what that "apply to both", > which is the central part of the operation, exactly means. > > The only mode of operation we offer is that we start from identical > index and working tree, and make the same change so that we arrive > at the same outcome. It is not like you can have some changes in > the working tree file as long as they do not overlap and collide > with the incoming patch, make the same change with the patch to > arrive at different contents as the outcome. We explicitly forbid > that, but "apply to both" does not exactly tell it to the readers. Your have point that the original text muddies the preconditions a bit, but I still think that "what it does" must be the first thing to be mentioned, and the preconditions the second. -- Hannes
