# symlink-or-copy

> Symlink files or directories, falling back to copying on Windows

Latest version **1.3.1** (published 2019-12-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install symlink-or-copy
pnpm add symlink-or-copy
yarn add symlink-or-copy
bun add symlink-or-copy
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.3.1 |
| Published | 2019-12-23 |
| First published | 2014-07-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/symlink-or-copy) |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 10.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Jo Liss |
| Maintainers | joliss, rwjblue, stefanpenner |

## Links

- npm: https://www.npmjs.com/package/symlink-or-copy
- Repository: https://github.com/broccolijs/node-symlink-or-copy
- Homepage: https://github.com/broccolijs/node-symlink-or-copy#readme
- Issues: https://github.com/broccolijs/node-symlink-or-copy/issues
- npm.io page: https://npm.io/package/symlink-or-copy

## Recent versions

- 1.3.1 (latest) — 2019-12-23
- 1.3.0 — 2019-12-06
- 1.2.0 — 2018-02-15
- 1.1.8 — 2016-11-27
- 1.1.7 — 2016-11-27
- 1.1.6 — 2016-08-05
- 1.1.5 — 2016-08-05
- 1.1.3 — 2016-04-25
- 1.1.2 — 2016-04-23
- 1.1.1 — 2016-04-17
- 1.1.0 — 2016-04-14
- 1.0.1 — 2014-11-28
- 1.0.0 — 2014-07-19

## README

# node-symlink-or-copy

[![Build Status](https://travis-ci.org/broccolijs/node-symlink-or-copy.svg?branch=master)](https://travis-ci.org/broccolijs/node-symlink-or-copy)
[![Build status](https://ci.appveyor.com/api/projects/status/rilxgmo21j3qth3v/branch/master?svg=true)](https://ci.appveyor.com/project/joliss/node-symlink-or-copy/branch/master)

Symlink a file or directory to another place. Fall back to copying on Windows.
Made for use with Broccoli plugins, for "do what I mean" behavior.

## Installation

```sh
npm install --save symlink-or-copy
```

## Example

```js
const symlinkOrCopySync = require('symlink-or-copy').sync;

symlinkOrCopySync('src_dir/some_file.txt', 'dest_dir/some_file.txt');
symlinkOrCopySync('src_dir/some_dir', 'dest_dir/some_dir');
```

## Description

```js
symlinkOrCopySync(srcPath, destPath);
```

Create a symlink at `destPath` pointing to `srcPath`.

On Windows, we may fall back to copying `srcPath` to `destPath`, preserving
last-modified times. However, do not *rely* on always getting a copy on
Windows (see Notes below).

If you pass a relative `srcPath`, it will be resolved relative to
`process.cwd()`, akin to a copy function. Note that this is unlike
[`fs.symlinkSync`](http://nodejs.org/api/fs.html#fs_fs_symlink_srcpath_dstpath_type_callback),
whose `srcPath` is relative to `destPath`.

If `srcPath` does not exist or is a broken symlink, we might throw an
exception, or we might create a broken symlink.

When we fall back to copying, symlinks at or beneath `srcPath` will be
dereferenced, and broken symlinks will cause exceptions.

We will throw an exception if `destPath` already exists. Thus in contrast to
Unix `cp` or `ln`, the following will fail:

```js
// dest_dir already exists, and we might expect dest_dir/some_dir to be
// created. This does not work; pass 'dest_dir/some_dir' instead.
symlinkOrCopySync('src_dir/some_dir', 'dest_dir');
```

It is an error if the parent directory of `destPath` does not already exist.

When we symlink, if the file at `srcPath` is a symlink as well, it will be
dereferenced before symlinking, to avoid runaway symlink indirection.

## Notes

* Symlinks technically work on Windows, but they require special rights. For
  users with those rights, symlinks are used, but when not available, a
  combination of junctions and copying is used to mimic the behavior somewhat
  performantly.

* There intentionally isn't an asynchronous version. It's not clear that we
  need or want one. Before sending a patch to add an async version, please
  share your use case on the issue tracker.

---
_Source: https://npm.io/package/symlink-or-copy · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._