feat: add --dereference-symlinks flag for recursive symlink resolution

add new --dereference-symlinks boolean flag that recursively resolves
all symlinks to their target content during file collection. this works
on symlinks inside directories, not just CLI arguments.

the flag is wired through cli/parse.go to boxo's SerialFileOptions.DereferenceSymlinks.

deprecate --dereference-args which only worked on symlinks passed directly
as CLI arguments. the help text now indicates it is deprecated and directs
users to use --dereference-symlinks instead.

ref: ipfs/specs#499

Author: lidel

cli/parse.go

@@ -84,6 +84,11 @@ func stdinName(req *cmds.Request) string {
 	return name
 }
 
+func dereferenceSymlinks(req *cmds.Request) bool {
+	deref, _ := req.Options[cmds.DerefSymlinks].(bool)
+	return deref
+}
+
 type parseState struct {
 	cmdline []string
 	i       int
@@ -324,7 +329,7 @@ func parseArgs(req *cmds.Request, root *cmds.Command, stdin *os.File) error {
 					if err != nil {
 						return err
 					}
-					nf, err := appendFile(fpath, argDef, isRecursive(req), filter)
+					nf, err := appendFile(fpath, argDef, isRecursive(req), filter, dereferenceSymlinks(req))
 					if err != nil {
 						return err
 					}
@@ -542,7 +547,7 @@ func getArgDef(i int, argDefs []cmds.Argument) *cmds.Argument {
 const notRecursiveFmtStr = "'%s' is a directory, use the '-%s' flag to specify directories"
 const dirNotSupportedFmtStr = "invalid path '%s', argument '%s' does not support directories"
 
-func appendFile(fpath string, argDef *cmds.Argument, recursive bool, filter *files.Filter) (files.Node, error) {
+func appendFile(fpath string, argDef *cmds.Argument, recursive bool, filter *files.Filter, dereferenceSymlinks bool) (files.Node, error) {
 	stat, err := os.Lstat(fpath)
 	if err != nil {
 		return nil, err
@@ -566,7 +571,10 @@ func appendFile(fpath string, argDef *cmds.Argument, recursive bool, filter *fil
 
 		return files.NewReaderFile(file), nil
 	}
-	return files.NewSerialFileWithFilter(fpath, filter, stat)
+	return files.NewSerialFileWithOptions(fpath, stat, files.SerialFileOptions{
+		Filter:              filter,
+		DereferenceSymlinks: dereferenceSymlinks,
+	})
 }
 
 // Inform the user if a file is waiting on input

go.mod

@@ -1,10 +1,10 @@
 module github.com/ipfs/go-ipfs-cmds
 
-go 1.24.0
+go 1.24.6
 
 require (
-	github.com/ipfs/boxo v0.34.0
-	github.com/ipfs/go-log/v2 v2.8.1
+	github.com/ipfs/boxo v0.35.3-0.20260117004328-4ff72d072c00
+	github.com/ipfs/go-log/v2 v2.9.0
 	github.com/rs/cors v1.11.1
 	github.com/texttheater/golang-levenshtein v1.0.1
 	golang.org/x/term v0.37.0

go.sum

@@ -2,18 +2,18 @@ github.com/crackcomm/go-gitignore v0.0.0-20241020182519-7843d2ba8fdf h1:dwGgBWn8
 github.com/crackcomm/go-gitignore v0.0.0-20241020182519-7843d2ba8fdf/go.mod h1:p1d6YEZWvFzEh4KLyvBcVSnrfNDDvK2zfK/4x2v/4pE=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
-github.com/ipfs/boxo v0.34.0 h1:pMP9bAsTs4xVh8R0ZmxIWviV7kjDa60U24QrlGgHb1g=
-github.com/ipfs/boxo v0.34.0/go.mod h1:kzdH/ewDybtO3+M8MCVkpwnIIc/d2VISX95DFrY4vQA=
-github.com/ipfs/go-log/v2 v2.8.1 h1:Y/X36z7ASoLJaYIJAL4xITXgwf7RVeqb1+/25aq/Xk0=
-github.com/ipfs/go-log/v2 v2.8.1/go.mod h1:NyhTBcZmh2Y55eWVjOeKf8M7e4pnJYM3yDZNxQBWEEY=
+github.com/ipfs/boxo v0.35.3-0.20260117004328-4ff72d072c00 h1:e9p5CizXgzPlnxt1kzDyYNoKusO4cvDjNG33UqyVhwM=
+github.com/ipfs/boxo v0.35.3-0.20260117004328-4ff72d072c00/go.mod h1:Abmp1if6bMQG87/0SQPIB9fkxJnZMLCt2nQw3yUZHH0=
+github.com/ipfs/go-log/v2 v2.9.0 h1:l4b06AwVXwldIzbVPZy5z7sKp9lHFTX0KWfTBCtHaOk=
+github.com/ipfs/go-log/v2 v2.9.0/go.mod h1:UhIYAwMV7Nb4ZmihUxfIRM2Istw/y9cAk3xaK+4Zs2c=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
 github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rs/cors v1.11.1 h1:eU3gRzXLRK57F5rKMGMZURNdIG4EoAmX8k94r9wXWHA=
 github.com/rs/cors v1.11.1/go.mod h1:XyqrcTp5zjWr1wsJ8PIRZssZ8b/WMcMf71DJnit4EMU=
-github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
-github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
 github.com/texttheater/golang-levenshtein v1.0.1 h1:+cRNoVrfiwufQPhoMzB6N0Yf/Mqajr6t1lOv8GyGE2U=
 github.com/texttheater/golang-levenshtein v1.0.1/go.mod h1:PYAKrbF5sAiq9wd+H82hs7gNaen0CplQ9uvm6+enD/8=
 go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=

opts.go

@@ -2,28 +2,30 @@ package cmds
 
 // Flag names
 const (
-	EncShort     = "enc"
-	EncLong      = "encoding"
-	RecShort     = "r"
-	RecLong      = "recursive"
-	ChanOpt      = "stream-channels"
-	TimeoutOpt   = "timeout"
-	OptShortHelp = "h"
-	OptLongHelp  = "help"
-	DerefLong    = "dereference-args"
-	StdinName    = "stdin-name"
-	Hidden       = "hidden"
-	HiddenShort  = "H"
-	Ignore       = "ignore"
-	IgnoreRules  = "ignore-rules-path"
+	EncShort      = "enc"
+	EncLong       = "encoding"
+	RecShort      = "r"
+	RecLong       = "recursive"
+	ChanOpt       = "stream-channels"
+	TimeoutOpt    = "timeout"
+	OptShortHelp  = "h"
+	OptLongHelp   = "help"
+	DerefLong     = "dereference-args"
+	DerefSymlinks = "dereference-symlinks"
+	StdinName     = "stdin-name"
+	Hidden        = "hidden"
+	HiddenShort   = "H"
+	Ignore        = "ignore"
+	IgnoreRules   = "ignore-rules-path"
 )
 
 // options that are used by this package
 var OptionEncodingType = StringOption(EncLong, EncShort, "The encoding type the output should be encoded with (json, xml, or text)").WithDefault("text")
 var OptionRecursivePath = BoolOption(RecLong, RecShort, "Add directory paths recursively")
 var OptionStreamChannels = BoolOption(ChanOpt, "Stream channel output")
 var OptionTimeout = StringOption(TimeoutOpt, "Set a global timeout on the command")
-var OptionDerefArgs = BoolOption(DerefLong, "Symlinks supplied in arguments are dereferenced")
+var OptionDerefArgs = BoolOption(DerefLong, "DEPRECATED: use --dereference-symlinks instead. Only dereferenced symlinks in CLI arguments, not inside directories.")
+var OptionDerefSymlinks = BoolOption(DerefSymlinks, "Recursively resolve all symlinks to their target content. Works on symlinks inside directories, not just CLI arguments.")
 var OptionStdinName = StringOption(StdinName, "Assign a name if the file source is stdin.")
 var OptionHidden = BoolOption(Hidden, HiddenShort, "Include files that are hidden. Only takes effect on recursive add.")
 var OptionIgnore = StringsOption(Ignore, "A rule (.gitignore-stype) defining which file(s) should be ignored (variadic, experimental)")