bug#32069: Man page description is wrong for -i

[Matthew Jenkins]

I'm not asking to change the behavior of sed. I'm asking to have the
man page reflect what sed -i actually does to at least be less wrong
so it's less of a gotcha.

Examples of gotchas:
sed -i on a large file when you only have less than that amount of
space available.
sed -i on a hard link

I'm sure there are more but these gotchas wouldn't be gotchas anymore
with a better description.

The item you linked doesn't really cover this.
On Fri, Jul 6, 2018 at 1:31 AM Assaf Gordon <address@hidden> wrote:
>
> tag 32069 notabug
> close 32069
> stop
>
> Hello Matthew,
>
> On 05/07/18 06:30 PM, Matthew Jenkins wrote:
> > In the man page the description for -i is as follows:
> >         -i[SUFFIX], --in-place[=SUFFIX]
> >
> >                edit files in place (makes backup if SUFFIX supplied)
> >
> > However the actual behavior is it's replacing the original with a copy
> > and not editing in place. This can cause confusion for why sed is
> > breaking hardlinks. Example:
> [....]
> > I'm pretty sure replacing with the copy is intentional behavior, so
> > can the manual be updated to reflect this?
>
> You are correct in observing that sed's "--in-place" behavior is
> replacing the file with a new copy (and optionally creating a backup).
>
> This has always been the "--in-place" behavior, both in GNU sed and in
> other seds (e.g. on FreeBSD). Same behavior is in other command-line
> "in-place" editing programs:
>
>     perl -p -i.bak -e 's/bar/baz/' FILE
>     ruby -p -i.bak -e '$_.upcase!' FILE
>
> The backup file (if you choose to create one) is the exact original file
> (with the same inode).
>
> Therefore I'm not sure if there should be an expectation that hard-links
> will be maintained - they have never been maintained by such in-place
> editing.
>
> Some interactive text editors (e.g. vim/nano) do keep the same inode,
> but they go to much greater lengths to do so safely.
>
> For an interesting write-up about the nuances of in-place editing in
> unix, please see here:
> https://www.pixelbeat.org/docs/unix_file_replacement.html .
>
>
> As such, I'm marking this item as "not a bug" and closing it,
> however discussion can continue by replying to this thread.
>
> If you want to suggest different wording to the "--help" usage screen
> or sed's manual, please send a patch - we welcome such contributions.
>
> regards,
>   - assaf
>