@actions/io: `mv(file, dest)` replaces `dest` when it is a symlink to a directory instead of moving into it

Open Beginner friendly
#2,570 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@bardrop is already working on this.

Since Nov 12, 2026.

  • #2576 by @bardrop — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
82/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
node.js, typescript
Domain
devtools

Research direction

Read packages/io/src/io.ts and trace how mv checks whether the destination is a directory; compare that check with io.cp and the isDirectory helper’s useStat behavior. Add or update a regression test for moving a file into a symlink to a directory, then confirm the symlink remains and the file appears in the target directory.

Written by the indexing model from the issue text.

Description

Describe the bug
io.mv checks whether dest is a directory with ioUtil.isDirectory(dest), which uses lstat by default. When dest is a symlink pointing to a directory, isDirectory(dest) returns false and dest is treated as an existing file. With the default force: true, the symlink is deleted and the source is renamed to the symlink's path; with force: false, it throws "Destination already exists". By contrast, mv(1) (which @actions/io documents mv as following) and io.cp (which uses stat) move/copy the source into the target directory.

To Reproduce
Run the following with @actions/io:

// repro.mjs
import * as io from '@actions/io'
import fs from 'fs'
fs.mkdirSync('real-dir')
fs.symlinkSync('real-dir', 'link-dir')
fs.writeFileSync('a.txt', 'hello')
await io.mv('a.txt', 'link-dir')
console.log('link-dir is symlink:', fs.lstatSync('link-dir').isSymbolicLink())
console.log('real-dir:', fs.readdirSync('real-dir'))
mkdir demo && cd demo && node ../repro.mjs

Actual output:

link-dir is symlink: false
real-dir: []

(link-dir is now the moved file.)

Expected behavior
Matching mv a.txt link-dir (GNU coreutils 9.1) and io.cp:

link-dir is symlink: true
real-dir: [ 'a.txt' ]

Screenshots
N/A

Desktop (please complete the following information):

  • OS: Linux (x86_64)
  • Browser: N/A
  • Version: @actions/io 3.0.2 (npm latest), actions/toolkit main 0c3a9c3, Node.js v26.13.0

Smartphone (please complete the following information):

  • Device: N/A
  • OS: N/A
  • Browser: N/A
  • Version: N/A

Additional context
In packages/io/src/io.ts, mv calls ioUtil.isDirectory(dest), whose useStat parameter defaults to false (lstat). Passing ioUtil.isDirectory(dest, true) would use stat and match io.cp and mv(1).

Credit: https://ucsbplse.github.io/

Dominant language
TypeScript
Stars
5.9k
Forks
1.8k
Avg merge
15m
Merged PRs (30d)
1

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from actions/toolkit

All issues in actions/toolkit

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.