Relative paths with subfolders fail in Finder due to LIST mode limitation

[timstoop]

Describe the bug

When using govc or the govmomi Finder API, relative paths containing subfolders (e.g., ParentFolder/SubFolder) fail to resolve, while absolute paths work correctly. This is caused by the Finder automatically switching to LIST mode for paths containing /, which only traverses immediate children instead of the full path hierarchy.

To Reproduce

Steps to reproduce the behavior:

1. Set up a vSphere environment with nested VM folders (e.g., /Datacenter/vm/Folder1/Folder2/Folder3/Folder4)
2. Set the datacenter context with govc datacenter.info
3. Try to access a subfolder using a relative path:

   $ govc folder.info Folder1/Folder2/Folder3/Folder4
   govc: folder 'Folder1/Folder2/Folder3/Folder4' not found

4. Try with absolute path:

   $ govc folder.info /Datacenter/vm/Folder1/Folder2/Folder3/Folder4
   Name:        Folder4
     Path:      /Datacenter/vm/Folder1/Folder2/Folder3/Folder4

5. Note that even listing children fails with relative paths:

   $ govc ls Folder1
   (no output)
   
   $ govc ls /Datacenter/vm/Folder1
   /Datacenter/vm/Folder1/Folder2

Expected behavior

Relative paths with subfolders should work the same as absolute paths, resolved relative to the datacenter's VM folder. Folder1/Folder2/Folder3/Folder4 should resolve to /Datacenter/vm/Folder1/Folder2/Folder3/Folder4 when the datacenter is set.

Single-level relative paths like Folder1 work correctly, so multi-level relative paths like Folder1/Folder2 should also work but currently fail.

Affected version

• govmomi version: main branch (commit 9d1d96b, 2025-10-31)
• Also affects: Cluster API Provider vSphere (CAPV) which uses govmomi Finder

Screenshots/Debug Output

Root cause analysis from code review:

In find/finder.go line 106, the code determines if something is a path by checking for /:

isPath := strings.Contains(arg, "/")

When isPath is true, it uses LIST mode (line 147-151), which calls Lister.ListFolder(). This method uses a TraversalSpec with only "childEntity" (list/lister.go line 165-169), retrieving only immediate children without recursively traversing the folder hierarchy.

Additional context

Impact:

1. Counter-intuitive UX: Adding specificity to a path causes it to fail
2. CAPV users must use absolute paths with datacenter prefix for nested folders, reducing portability
3. Workarounds (absolute paths or ... wildcard) are not well documented

Workarounds:

• Use absolute paths: /Datacenter/vm/Folder1/Folder2/Folder3/Folder4
• Use ... wildcard for recursive search (when applicable)

Possible solutions:

1. Make LIST mode recursively traverse multi-segment paths
2. Only use LIST mode for absolute paths (starting with /)

[github-actions]

Howdy 🖐   timstoop ! Thank you for your interest in this project. We value your feedback and will respond soon.

If you want to contribute to this project, please make yourself familiar with the CONTRIBUTION guidelines.

[github-actions]

This issue is stale because it has been open for 90 days with no
activity. It will automatically close after 30 more days of
inactivity. Mark as fresh by adding the comment /remove-lifecycle stale.