GNU bug report logs - #32069
Man page description is wrong for -i

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 32069 in the body.
You can then email your comments to 32069 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Matthew Jenkins <mjenki03 <at> gmail.com>
To: bug-sed <at> gnu.org
Subject: Man page description is wrong for -i
Date: Thu, 5 Jul 2018 19:30:15 -0500

[mjenkins <at> hulk ~]$ sed --version
sed (GNU sed) 4.5
Copyright (C) 2018 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by Jay Fenlason, Tom Lord, Ken Pizzini,
and Paolo Bonzini.
GNU sed home page: <https://www.gnu.org/software/sed/>.
General help using GNU software: <https://www.gnu.org/gethelp/>.
E-mail bug reports to: <bug-sed <at> gnu.org>.




On Fedora 28.

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:

[mjenkins <at> hulk test]$ touch banana
[mjenkins <at> hulk test]$ stat banana | grep Inode
Device: fd07h/64775d Inode: 8782051     Links: 1
[mjenkins <at> hulk test]$ sed -i '' banana
[mjenkins <at> hulk test]$ stat banana | grep Inode
Device: fd07h/64775d Inode: 8781989     Links: 1

I'm pretty sure replacing with the copy is intentional behavior, so
can the manual be updated to reflect this?


Thanks,
Matthew

Message #8 received at 32069 <at> debbugs.gnu.org (full text, mbox):

From: Assaf Gordon <assafgordon <at> gmail.com>
To: Matthew Jenkins <mjenki03 <at> gmail.com>, 32069 <at> debbugs.gnu.org
Subject: Re: bug#32069: Man page description is wrong for -i
Date: Fri, 6 Jul 2018 00:31:49 -0600

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

Message #15 received at 32069 <at> debbugs.gnu.org (full text, mbox):

From: Matthew Jenkins <mjenki03 <at> gmail.com>
To: assafgordon <at> gmail.com
Cc: 32069 <at> debbugs.gnu.org
Subject: Re: bug#32069: Man page description is wrong for -i
Date: Fri, 6 Jul 2018 15:54:29 -0500

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 <assafgordon <at> gmail.com> 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
>

Message #18 received at 32069 <at> debbugs.gnu.org (full text, mbox):

From: Assaf Gordon <assafgordon <at> gmail.com>
To: Matthew Jenkins <mjenki03 <at> gmail.com>
Cc: 32069 <at> debbugs.gnu.org
Subject: Re: bug#32069: Man page description is wrong for -i
Date: Fri, 6 Jul 2018 15:43:01 -0600

Hello,

On 06/07/18 02:54 PM, Matthew Jenkins wrote:
> 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

when out of disk space, 'sed -i' behaves in a very reasonable and safe way:
it will fail to create the temporary file, and leave the original file 
unmodified.

As for 'sed -i' on hard-link:
"sed -i" has never maintained hard-links with "--in-place",
and neither does any other common unix utility - so it is not clear
where this expectation originates from.


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

"sed -i" certainly has some gotchas, and few are documented in the manual:
https://www.gnu.org/software/sed/manual/sed.html#index-_002df

It seems the "in-place" related topics are growing, perhaps it is
warranted to dedicated a separate section in the manual.

If you'd like to try and add such a section - please do send a patch.

Otherwise, I will try to add something like that at a later time.

regards,
 - assaf

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.