docs: add documentation for the commands: up, list, new and remove

docs/astro.config.mjs

@@ -12,6 +12,9 @@ export default defineConfig({
       editLink: {
         baseUrl: 'https://github.com/aboviq/emigrate/edit/main/docs/',
       },
+      components: {
+        PageTitle: './src/components/PageTitle.astro',
+      },
       sidebar: [
         {
           label: 'Introduction',
@@ -26,6 +29,27 @@ export default defineConfig({
             },
           ],
         },
+        {
+          label: 'Commands',
+          items: [
+            {
+              label: 'emigrate up',
+              link: '/commands/up/',
+            },
+            {
+              label: 'emigrate list',
+              link: '/commands/list/',
+            },
+            {
+              label: 'emigrate new',
+              link: '/commands/new/',
+            },
+            {
+              label: 'emigrate remove',
+              link: '/commands/remove/',
+            },
+          ],
+        },
         {
           label: 'Plugins',
           items: [

docs/src/components/PageTitle.astro

@@ -0,0 +1,27 @@
+---
+import type { Props } from '@astrojs/starlight/props';
+
+const { title } = Astro.props.entry.data;
+const isCode = title.startsWith('`') && title.endsWith('`');
+---
+
+<h1 id="_top">{isCode ? <code>{title.slice(1, -1)}</code> : title}</h1>
+
+<style>
+  h1 {
+    margin-top: 1rem;
+    font-size: var(--sl-text-h1);
+    line-height: var(--sl-line-height-headings);
+    font-weight: 600;
+    color: var(--sl-color-white);
+  }
+
+  code {
+    font-family: var(--sl-font-system-mono);
+    background-color: var(--sl-color-bg-inline-code);
+    border: 1px solid var(--sl-color-gray-3);
+    color: var(--sl-color-gray-1);
+    padding: 0.25rem 0.5rem;
+    border-radius: 0.25rem;
+  }
+</style>

docs/src/content/docs/commands/list.mdx

@@ -0,0 +1,55 @@
+---
+title: "`emigrate list`"
+description: "List migrations and their status."
+---
+
+The `list` command is used to list _all_ migrations, i.e. both already run migrations and migrations that haven't been run yet.
+
+Emigrate takes all migration files in the given directory that haven't been run yet and all migrations from the migration history.  
+It then sorts the migrations by filename in ascending order and outputs them and their respective status one by one.
+
+## Usage
+
+```bash
+emigrate list [options]
+```
+
+## Options
+
+### `-h`, `--help`
+
+Show command help and exit
+
+### `-d`, `--directory <path>`
+
+The directory where the migration files are located. The given path should be absolute or relative to the current working directory.
+
+### `-s`, `--storage <name>`
+
+The storage to use for where to read the migration history.
+
+The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
+
+- `@emigrate/storage-`
+- `emigrate-storage-`
+- `@emigrate/plugin-storage-`
+- `@emigrate/`
+
+And then try to load the module/package with the given name.
+
+For example, if you want to use the `emigrate-storage-somedb` package, you can specify either `emigrate-storage-somedb` or just `somedb` as the name.
+In case you have both a `emigrate-storage-somedb` and a `somedb` package installed, the `emigrate-storage-somedb` package will be used.
+
+### `-r`, `--reporter <name>`
+
+The reporter to use for listing the migrations.
+
+The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
+
+- `@emigrate/reporter-`
+- `emigrate-reporter-`
+- `@emigrate/`
+
+And then try to load the module/package with the given name.
+
+For example, if you want to use the `emigrate-reporter-somereporter` package, you can specify either `emigrate-reporter-somereporter` or just `somereporter` as the name.

docs/src/content/docs/commands/new.mdx

@@ -0,0 +1,72 @@
+---
+title: "`emigrate new`"
+description: "Create new migration."
+---
+
+The `new` command is used to create a new migration file in the given directory.
+
+The migration file can be based on a template, generated by a [generator plugin](/plugins/generators/), or just be an empty file.
+
+## Usage
+
+```bash
+emigrate new [options] <name>
+```
+
+## Arguments
+
+### `<name>`
+
+The name of the migration. The name will be used to generate the migration filename.
+
+The name can be provided as a single argument or as multiple arguments.
+If multiple arguments are provided, the arguments will be joined with a space before being passed to the filename generator (the default filename generator replaces all whitespace and non-path safe characters with underscores).
+
+## Options
+
+### `-h`, `--help`
+
+Show command help and exit
+
+### `-d`, `--directory <path>`
+
+The directory where the migration files are located. The given path should be absolute or relative to the current working directory.
+
+### `-t`, `--template <path>`
+
+The template file to use for generating the migration file. The given path should be absolute or relative to the current working directory.
+
+The template can contain a `{{name}}` placeholder which will be replaced with the migration name provided to the command. The generated file will have the same extension as the template file, unless the [`--extension`](#e---extension-ext) option is used.
+
+### `-e`, `--extension <ext>`
+
+The extension to use for the migration file. Unless the [`--template`](#t---template-path) option is also specified the file will be empty.
+
+### `-p`, `--plugin <name>`
+
+The [generator plugin](/plugins/generators/) to use. The generator plugin is responsible for generating the migration filename and its contents.
+
+The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
+
+- `@emigrate/plugin-`
+- `emigrate-plugin-`
+- `@emigrate/`
+
+And then try to load the module/package with the given name.
+
+For example, if you want to use the `emigrate-plugin-someplugin` package, you can specify either `emigrate-plugin-someplugin` or just `someplugin` as the name.
+In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package installed, the `emigrate-plugin-someplugin` package will be used.
+
+### `-r`, `--reporter <name>`
+
+The reporter to use for listing the migrations.
+
+The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
+
+- `@emigrate/reporter-`
+- `emigrate-reporter-`
+- `@emigrate/`
+
+And then try to load the module/package with the given name.
+
+For example, if you want to use the `emigrate-reporter-somereporter` package, you can specify either `emigrate-reporter-somereporter` or just `somereporter` as the name.

docs/src/content/docs/commands/remove.mdx

@@ -0,0 +1,62 @@
+---
+title: "`emigrate remove`"
+description: "Remove a migration from the history."
+---
+
+The `remove` command is used to remove a migration from the history. This is useful if you want to retry a migration that has failed.
+
+## Usage
+
+```bash
+emigrate remove [options] <name>
+```
+
+## Arguments
+
+### `<name>`
+
+The name of the migration file to remove, including the extension, e.g. `20200101000000_some_migration.js`.
+
+## Options
+
+### `-h`, `--help`
+
+Show command help and exit
+
+### `-d`, `--directory <path>`
+
+The directory where the migration files are located. The given path should be absolute or relative to the current working directory.
+
+### `-f`, `--force`
+
+Force removal of the migration history entry even if the migration file does not exist or it's in a non-failed state.
+
+### `-s`, `--storage <name>`
+
+The storage to use for where to read the migration history.
+
+The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
+
+- `@emigrate/storage-`
+- `emigrate-storage-`
+- `@emigrate/plugin-storage-`
+- `@emigrate/`
+
+And then try to load the module/package with the given name.
+
+For example, if you want to use the `emigrate-storage-somedb` package, you can specify either `emigrate-storage-somedb` or just `somedb` as the name.
+In case you have both a `emigrate-storage-somedb` and a `somedb` package installed, the `emigrate-storage-somedb` package will be used.
+
+### `-r`, `--reporter <name>`
+
+The reporter to use for listing the migrations.
+
+The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
+
+- `@emigrate/reporter-`
+- `emigrate-reporter-`
+- `@emigrate/`
+
+And then try to load the module/package with the given name.
+
+For example, if you want to use the `emigrate-reporter-somereporter` package, you can specify either `emigrate-reporter-somereporter` or just `somereporter` as the name.

docs/src/content/docs/commands/up.mdx

@@ -0,0 +1,76 @@
+---
+title: "`emigrate up`"
+description: "Run migrations"
+---
+
+The `up` command is used to either list or run all pending migrations, i.e. migrations that haven't been run yet.
+
+Emigrate takes all migration files in the given directory and compares them to the migration history so that it knows which migrations are pending.  
+It then sorts the pending migrations by filename in ascending order and runs them one by one.
+
+If any of the migrations fail, the command will be aborted and the rest of the migrations will not be run.
+
+## Usage
+
+```bash
+emigrate up [options]
+```
+
+## Options
+
+### `-h`, `--help`
+
+Show command help and exit
+
+### `--dry`
+
+List the pending migrations that would be run without actually running them
+
+### `-d`, `--directory <path>`
+
+The directory where the migration files are located. The given path should be absolute or relative to the current working directory.
+
+### `-s`, `--storage <name>`
+
+The storage to use for where to store the migration history.
+
+The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
+
+- `@emigrate/storage-`
+- `emigrate-storage-`
+- `@emigrate/plugin-storage-`
+- `@emigrate/`
+
+And then try to load the module/package with the given name.
+
+For example, if you want to use the `emigrate-storage-somedb` package, you can specify either `emigrate-storage-somedb` or just `somedb` as the name.
+In case you have both a `emigrate-storage-somedb` and a `somedb` package installed, the `emigrate-storage-somedb` package will be used.
+
+### `-p`, `--plugin <name>`
+
+The [loader plugin(s)](/plugins/loaders/) to use. Can be specified multiple times to use multiple plugins.
+
+The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
+
+- `@emigrate/plugin-`
+- `emigrate-plugin-`
+- `@emigrate/`
+
+And then try to load the module/package with the given name.
+
+For example, if you want to use the `emigrate-plugin-someplugin` package, you can specify either `emigrate-plugin-someplugin` or just `someplugin` as the name.
+In case you have both a `emigrate-plugin-someplugin` and a `someplugin` package installed, the `emigrate-plugin-someplugin` package will be used.
+
+### `-r`, `--reporter <name>`
+
+The reporter to use for reporting the migration progress.
+
+The name can be either a path to a module or a package name. For package names Emigrate will automatically prefix the given name with these prefixes in order:
+
+- `@emigrate/reporter-`
+- `emigrate-reporter-`
+- `@emigrate/`
+
+And then try to load the module/package with the given name.
+
+For example, if you want to use the `emigrate-reporter-somereporter` package, you can specify either `emigrate-reporter-somereporter` or just `somereporter` as the name.