feat: add --dereference-symlinks flag for recursive symlink resolution (#315)

* 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

* fix: make --dereference-symlinks resolve CLI arg symlinks too

--dereference-symlinks is now a superset of --dereference-args:
- resolves symlinks passed as CLI arguments (like --dereference-args)
- ALSO resolves symlinks found during directory traversal (new behavior)

this allows users to use just --dereference-symlinks instead of needing
to pass both flags for full symlink resolution.

* chore: update to rebased boxo PR

updates github.com/ipfs/boxo to 56cf0aecdc1a (feat/ipip-499-unixfs-2025 rebased on main)

* fix: reuse derefSymlinks variable, fix typo in deprecation notice

* chore: update boxo to f188f79fd412

switches to boxo@main after merging ipfs/boxo#1088

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
@@ -303,6 +308,7 @@ func parseArgs(req *cmds.Request, root *cmds.Command, stdin *os.File) error {
 				} else {
 					fpath = filepath.Clean(fpath)
 					derefArgs, _ := req.Options[cmds.DerefLong].(bool)
+					derefSymlinks := dereferenceSymlinks(req)
 					var err error
 
 					switch {
@@ -313,7 +319,7 @@ func parseArgs(req *cmds.Request, root *cmds.Command, stdin *os.File) error {
 						}
 						fpath = filepath.ToSlash(cwd)
 						fallthrough
-					case derefArgs:
+					case derefArgs || derefSymlinks:
 						if fpath, err = filepath.EvalSymlinks(fpath); err != nil {
 							return err
 						}
@@ -324,7 +330,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, derefSymlinks)
 					if err != nil {
 						return err
 					}
@@ -542,7 +548,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 +572,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

@@ -3,7 +3,7 @@ module github.com/ipfs/go-ipfs-cmds
 go 1.24.6
 
 require (
-	github.com/ipfs/boxo v0.36.0
+	github.com/ipfs/boxo v0.36.1-0.20260204203152-f188f79fd412
 	github.com/ipfs/go-log/v2 v2.9.1
 	github.com/rs/cors v1.11.1
 	github.com/texttheater/golang-levenshtein v1.0.1

go.sum

@@ -2,8 +2,8 @@ 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.36.0 h1:DarrMBM46xCs6GU6Vz+AL8VUyXykqHAqZYx8mR0Oics=
-github.com/ipfs/boxo v0.36.0/go.mod h1:92hnRXfP5ScKEIqlq9Ns7LR1dFXEVADKWVGH0fjk83k=
+github.com/ipfs/boxo v0.36.1-0.20260204203152-f188f79fd412 h1:nfRIkMIhetCWD8jw5ya+FY+jn9ii2c+U5gdkmSS4L1Q=
+github.com/ipfs/boxo v0.36.1-0.20260204203152-f188f79fd412/go.mod h1:92hnRXfP5ScKEIqlq9Ns7LR1dFXEVADKWVGH0fjk83k=
 github.com/ipfs/go-log/v2 v2.9.1 h1:3JXwHWU31dsCpvQ+7asz6/QsFJHqFr4gLgQ0FWteujk=
 github.com/ipfs/go-log/v2 v2.9.1/go.mod h1:evFx7sBiohUN3AG12mXlZBw5hacBQld3ZPHrowlJYoo=
 github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=

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 dereferences 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)")