On Tue, Jul 21, 2020 at 09:41:42AM -0600, Tracey Emery wrote:
> On Sun, Jul 19, 2020 at 06:54:41PM +0200, Stefan Sperling wrote:
> > +.It Fl S
> > +Allow symbolic links which point somewhere outside of the path space
> > +managed by
> > +.Nm .
> 
> #commas
> Allow symbolic links, which point somewhere outside of the path space,

It seems to me that adding a comma after "path space" changes the intended
meaning of the sentence.

Consider:

  1) Allow symbolic links which point somewhere outside of the path space
     managed by got.

  2) Allow symbolic links, which point somewhere outside of the path space,
     managed by got.

In the second version the "symbolic links" are being managed, aren't they?
In the first version the "path space" is being managed which is what I meant
to convey.

I propose to rewrite the entire paragraph in more detail to hopefully
make the intended meaning clear. What do you think?

diff 41806587196ab5f410de18aee2567cac7deb5d6b /home/stsp/src/got
blob - 1bd20230e857c83cb4e2cbd62cec36b1a83b09ab
file + got/got.1
--- got/got.1
+++ got/got.1
@@ -1228,14 +1228,20 @@ option,
 .Cm got commit
 opens a temporary file in an editor where a log message can be written.
 .It Fl S
-Allow symbolic links which point somewhere outside of the path space
-managed by
-.Nm .
+Allow the addition of symbolic links which point outside of the path space
+that is under version control.
+By default,
+.Cm got commit
+will reject such symbolic links due to safety concerns.
 As a precaution,
-when such a symbolic link gets installed in a work tree
 .Nm
-may decide to represent the symbolic link as a regular file which contains
-the link's target path, rather than creating an actual symbolic link.
+may decide to represent such a symbolic link as a regular file which contains
+the link's target path, rather than creating an actual symbolic link which
+points outside of the work tree.
+Use of this option is discouraged because external mechanisms such as
+.Dq make obj
+are suited better for managing symbolic links to paths that are not under
+version control.
 .El
 .Pp
 .Cm got commit
@@ -1723,14 +1729,20 @@ responses line-by-line from the specified
 .Ar response-script
 file instead of prompting interactively.
 .It Fl S
-Allow symbolic links which point somewhere outside of the path space
-managed by
-.Nm .
+Allow staging of symbolic links which point outside of the path space
+that is under version control.
+By default,
+.Cm got stage
+will reject such symbolic links due to safety concerns.
 As a precaution,
-when such a symbolic link gets installed in a work tree
 .Nm
-may decide to represent the symbolic link as a regular file which contains
-the link's target path, rather than creating an actual symbolic link.
+may decide to represent such a symbolic link as a regular file which contains
+the link's target path, rather than creating an actual symbolic link which
+points outside of the work tree.
+Use of this option is discouraged because external mechanisms such as
+.Dq make obj
+are suited better for managing symbolic links to paths that are not under
+version control.
 .El
 .Pp
 .Cm got stage