Re: [PATCH] docs: give more hints about how "add -e" works

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Jeff King <peff@xxxxxxxx> writes:

> Perhaps the list should be structured not as "what you can do to each
> line" but rather "here are some _concepts_ you might see, here's how
> they are represented, and how you might want to edit them". So
> basically:
>
>   - added lines; represented by "+" lines. You can prevent staging any
>     addition lines by deleting them.
>
>   - removed lines; represented by "-" lines. You can prevent staging any
>     removal lines by converting "-" to " ".
>
>   - modified lines; represented by "-" followed by "+". You can prevent
>     staging the modification by converting the "-" to a " ", and
>     removing the "+" lines. And this would be a good place to warn that
>     just deleting half of the pair is going to cause problems.
>
>   - existing lines; represented by " " lines. You can:
>
>       - remove them, by converting " " to "-".
>
>       - modify them, by converting " " to "-", and adding a new "+" line
>         with the new content.
>
>   - adding new lines; do not yet exist in the patch. You can add new
>     lines by inserting "+" lines with the new content.
>
> which is perhaps better, as it directs the user according to what they
> actually want to accomplish.

Yes, the above reads much better than starting from "when you see a '+'
you can do..." (which I think is a wrong approach that is backwards).

>> Is there a way to move this note way upwards?  Once the reader understands
>> what this paragraph teaches, it becomes much easier to understand the
>> implication of "remove addition".
>
> I agree it would be better at the top, but I think formatting it as I
> just wrote above would mean we can actually explain the issue in a more
> appropriate place. And then this bottom warning can just go away.

Agreed, again.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html


[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]