# shipit-shared

> Symlink unsourced files and directories, like Capistrano.

Latest version **4.4.2** (published 2016-11-22) · MIT license · 0 weekly downloads

## Install

```sh
npm install shipit-shared
pnpm add shipit-shared
yarn add shipit-shared
bun add shipit-shared
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.4.2 |
| Published | 2016-11-22 |
| First published | 2015-01-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 9 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 46 |
| Author | Tim Kelty |
| Maintainers | fusionary, timkelty |
| Keywords | shipit, deploy, task |

## Links

- npm: https://www.npmjs.com/package/shipit-shared
- Repository: https://github.com/timkelty/shipit-shared
- Issues: https://github.com/timkelty/shipit-shared/issues
- npm.io page: https://npm.io/package/shipit-shared

## Dependencies (9)

- [chalk](https://npm.io/package/chalk.md) ^1.1.1
- [path2](https://npm.io/package/path2.md) ^0.1.0
- [lodash](https://npm.io/package/lodash.md) ^4.12.0
- [mkdirp](https://npm.io/package/mkdirp.md) ^0.5.0
- [bluebird](https://npm.io/package/bluebird.md) ^3.0.6
- [sprintf-js](https://npm.io/package/sprintf-js.md) ^1.0.2
- [shipit-utils](https://npm.io/package/shipit-utils.md) ^1.0.2
- [shipit-deploy](https://npm.io/package/shipit-deploy.md) ^2.1.2
- [path-is-absolute](https://npm.io/package/path-is-absolute.md) ^1.0.0

## Recent versions

- 4.4.2 (latest) — 2016-11-22
- 4.4.1 — 2016-02-15
- 4.4.0 — 2016-01-25
- 4.3.0 — 2015-12-11
- 4.2.0 — 2015-11-20
- 4.1.7 — 2015-09-17
- 4.1.6 — 2015-09-09
- 4.1.4 — 2015-07-21
- 4.1.3 — 2015-07-21
- 4.1.2 — 2015-07-15
- 4.1.1 — 2015-07-15
- 4.1.0 — 2015-07-14
- 4.0.3 — 2015-07-09
- 3.2.0 — 2015-07-08
- 3.1.1 — 2015-05-18
- … 22 more at https://npm.io/package/shipit-shared/versions

## README

# shipit-shared

[![Build Status](https://travis-ci.org/timkelty/shipit-shared.svg)](https://travis-ci.org/timkelty/shipit-shared)
[![Dependency Status](https://david-dm.org/timkelty/shipit-shared.svg)](https://david-dm.org/timkelty/shipit-shared)
[![devDependency Status](https://david-dm.org/timkelty/shipit-shared/dev-status.svg)](https://david-dm.org/timkelty/shipit-shared#info=devDependencies)
[![Join the chat at https://gitter.im/timkelty/shipit-shared](https://img.shields.io/badge/gitter-join%20chat%20%E2%86%92-brightgreen.svg)](https://gitter.im/timkelty/shipit-shared?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

A set of tasks for [Shipit](https://github.com/shipitjs/shipit) used for symlinking persistent (un-sourced) files and directories on deploy.

Based on the concept of `linked_files`/`linked_dirs` from [Capistrano](http://capistranorb.com/documentation/getting-started/configuration/)

**Features:**

- By default, the `shared` task is triggered on the `updated` event from [shipit-deploy](https://github.com/shipitjs/shipit-deploy)
- All necessary directories are always created for you, whether you are linking a file or a directory.
- Optionally set permissions on files.
- Works via [shipit-cli](https://github.com/shipitjs/shipit) and [grunt-shipit](https://github.com/shipitjs/grunt-shipit)

**Roadmap**

- Optionally copy example files, such as example config files

## Install

```
npm install shipit-shared
```

## Usage

### Example `shipitfile.js`

```js
module.exports = function (shipit) {
  require('shipit-deploy')(shipit);
  require('shipit-shared')(shipit);

  shipit.initConfig({
    default: {
      shared: {
        overwrite: true,
        dirs: [
          'public/storage',
          {
            path: 'db',
            overwrite: false,
            chmod: '-R 777',
          }
        ],
        files: [
          'config/environment.yml',
          {
            path: 'config/database.yml',
            overwrite: false,
            chmod: '755',
          }
        ],
      }
    }
  });
};
```

To trigger on the deploy `published` event, you can simply deploy:

```
shipit staging deploy
```

Or you can run the tasks separately :

```
shipit staging shared
    shipit staging shared:create-dirs
    shipit staging shared:link
        shipit staging shared:link:dirs
        shipit staging shared:link:files
```

## Options `shipit.config.shared`

### `shared.dirs`, `shared.files`

Type: `Array`

An array of files/directories to symlink into `current`. String values inherit default settings, objects allow per-item configuration:

```
'public/storage'
{
  path: 'db',
  overwrite: true,
  chmod: '-R 777'
}
```

#### `path`

Type: `String`

Path to the shared file/directory (relative to `current`). 

#### `overwrite`

Type: `Boolean`

If the target of the symlink exists in `current`, remove it before creating symlink.

#### `chmod`

Type: `String`

Options passed to the `chmod` command for the given path. 

### `shared.basePath`

Type: `String`
Default: `path.join(shipit.config.deployTo, 'shared')`

The path where your shared files reside.

### `shared.overwrite`

Type: `Boolean`
Default: `false`

If `true`, the target of your symlink (in `current`), **will be removed (via rm -rf)** before creating the symlink. Under normal circumstances, this is fine, as files in `current` have come directly from a git checkout.

If `false` and the target of your symlink is a file or directory, and error is thrown and the task aborted.

The default setting of `false` is a safety precaution to prevent unintentionally losing data. See https://github.com/timkelty/shipit-shared/issues/17

### `shared.symlinkPath`

Type: `String`
Default: `shared.basePath`

The path that will serve as the source for your symlink. This is usually the same as `shared.basePath`, however it can be [necessary to set this in a `chroot` environment](https://github.com/timkelty/shipit-shared/issues/7).

### `shared.triggerEvent`
Type: `String`, `Boolean`
Default: `updated`

Trigger `shared` task on given event name.
Set to `false` to prevent task from listening to any events.
(note: Some part of shipit-shared *besides initConfig* needs to be run before it can listen for events)

## Events
- `shared`
  + `shared:prepare`
    + `shared:create-dirs`
      * Emit event `sharedDirsCreated`
    + `shared:set-permissions`
      * Emit event `sharedPermissionsSet`
  + `shared:link`
    + `shared:link-dirs`
      * Emit event `sharedFilesDirs`
    + `shared:link-files`
      * Emit event `sharedFilesLinked`
  + `shared:end`
    * Emit event `sharedEnd`

## License

MIT

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