Skip to content

Commit cd6e66b

Browse files
zackkatzzackkatz
authored
docs(gravitymigrate): add WP-CLI reference page + sidebar link (#14)
Adds an authored src/pages/gravitymigrate/cli.md route (route /gravitymigrate/cli/) documenting the `wp gk migrate` commands (export/import/inspect/status/reset), the data types, --porcelain/--format scripting, and the import safety-limit filters. Adds sidebars-gravitymigrate.js, which appends a "Command line (WP-CLI)" link to the GravityMigrate docs sidebar (mirroring the GravityView theming link), wired via a product branch in docusaurus.config.js. The page lives in src/pages/ because docs/ is generated and gitignored. Claude-Session: https://claude.ai/code/session_017AMC5bVpEM9G3WtXbXtmwj
1 parent a0c51f2 commit cd6e66b

3 files changed

Lines changed: 218 additions & 2 deletions

File tree

‎docusaurus.config.js‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -185,10 +185,14 @@ const product_docs_plugins = config_products
185185
routeBasePath: `docs/${product.id}`,
186186
tagsBasePath: 'since',
187187
};
188-
// GravityView uses a custom sidebar that appends a link to the theming
189-
// (CSS Design Tokens) page; every other product uses the default sidebars.js.
188+
// These products use a custom sidebar that appends a link to an authored
189+
// src/pages route (theming for GravityView, WP-CLI for GravityMigrate),
190+
// which the autogenerated sidebar can't reach; other products use the
191+
// default sidebars.js.
190192
if (product.id === 'gravityview') {
191193
options.sidebarPath = './sidebars-gravityview.js';
194+
} else if (product.id === 'gravitymigrate') {
195+
options.sidebarPath = './sidebars-gravitymigrate.js';
192196
}
193197
return ['@docusaurus/plugin-content-docs', options];
194198
});

‎sidebars-gravitymigrate.js‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
// @ts-check
2+
3+
/**
4+
* GravityMigrate-specific sidebar.
5+
*
6+
* Same autogenerated tree as the shared sidebars.js, plus a manual link to the
7+
* WP-CLI reference. That page lives at /gravitymigrate/cli/ as a src/pages route
8+
* — it is NOT a doc under docs/gravitymigrate/, so the autogenerated sidebar
9+
* can't pick it up on its own.
10+
*/
11+
12+
/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
13+
const sidebars = {
14+
mainSidebar: [
15+
{ type: 'autogenerated', dirName: '.' },
16+
{
17+
type: 'link',
18+
label: 'Command line (WP-CLI)',
19+
href: '/gravitymigrate/cli/',
20+
},
21+
],
22+
};
23+
24+
export default sidebars;

‎src/pages/gravitymigrate/cli.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
title: "GravityMigrate command line (WP-CLI)"
3+
description: "WP-CLI reference for GravityMigrate: export, import, inspect, status, and reset a migration bundle from the command line, including scripting with --porcelain and --format=json and the filters that tune import safety limits."
4+
---
5+
6+
# Command line (WP-CLI)
7+
8+
GravityMigrate registers a `wp gk migrate` command for running migrations without the browser. It exports a portable ZIP bundle, imports one, inspects one, and clears stuck migration state. Export and import drive the same batch state machine the admin screens use, run to completion synchronously in a single command.
9+
10+
The commands are available once GravityMigrate is active. GravityKit Foundation, bundled with the plugin, registers the top-level `wp gk` namespace.
11+
12+
:::note Administrator required
13+
`export`, `import`, and `reset` read or write your Gravity Forms and GravityView data, so they require an administrator. Pass `--user=` with an administrator's username or ID (for example `--user=admin`). `inspect` and `status` are read-only and do not require it.
14+
:::
15+
16+
## Commands
17+
18+
| Command | Purpose |
19+
| --- | --- |
20+
| `wp gk migrate export` | Export forms and their data to a ZIP bundle. |
21+
| `wp gk migrate import` | Import a bundle into this site. |
22+
| `wp gk migrate inspect` | Print a bundle's contents without importing it. |
23+
| `wp gk migrate status` | Report whether a migration is in progress or state is left over. |
24+
| `wp gk migrate reset` | Clear stuck migration state. |
25+
26+
## `wp gk migrate export`
27+
28+
Exports Gravity Forms and GravityKit data to a portable ZIP bundle.
29+
30+
| Option | Description |
31+
| --- | --- |
32+
| `--forms=<ids>` | Comma-separated form IDs to export, or `all`. Required. |
33+
| `--data=<types>` | Comma-separated [data types](#data-types), or `all`. Default: `entries,views,posts`. |
34+
| `--date-start=<Y-m-d>` | Only export entries created on or after this date. |
35+
| `--date-end=<Y-m-d>` | Only export entries created on or before this date. |
36+
| `--password=<password>` | Encrypt the ZIP (AES-256). |
37+
| `--public-url=<url>` | Rewrite this site's origin to `<url>` in exported upload URLs, page content, and `info.json`. Use it when the site's stored URL is not reachable from the destination so uploads download on import. The URL must be public and resolvable from the importing server. |
38+
| `--output=<path>` | Copy the finished ZIP to this path (the export directory is auto-deleted after three hours). |
39+
| `--porcelain` | Output only the resulting ZIP path. |
40+
| `--format=<format>` | Summary format: `table` (default) or `json`. |
41+
42+
```bash
43+
# Export one form with entries, Views, and the pages that embed them
44+
wp gk migrate export --forms=2 --user=admin
45+
46+
# Export everything, encrypted, to a specific path
47+
wp gk migrate export --forms=all --data=all --password=s3cret \
48+
--output=/srv/bundles/site.zip --user=admin
49+
50+
# Export from a demo clone whose stored URL is not publicly reachable
51+
wp gk migrate export --forms=2 --public-url=https://example.demo.gravitykit.com \
52+
--output=/srv/bundles/demo.zip --porcelain --user=admin
53+
```
54+
55+
## `wp gk migrate import`
56+
57+
Imports a GravityMigrate ZIP bundle into this site.
58+
59+
:::warning Imports are not resumable
60+
If an import fails partway, it prints the form IDs it committed before the failure. Delete those forms, run `wp gk migrate reset`, then re-run the import to get back to a clean state.
61+
:::
62+
63+
| Option | Description |
64+
| --- | --- |
65+
| `<zip>` | Path to the GravityMigrate export ZIP. Required. |
66+
| `--forms=<ids>` | Comma-separated source form IDs to import, or `all` (from the bundle). Default: `all`. |
67+
| `--data=<types>` | Comma-separated [data types](#data-types) to import, or `all` (intersected with the bundle). Default: `all`. |
68+
| `--password=<password>` | ZIP password, if it was encrypted. |
69+
| `--skip-uploads` | Do not download entry file uploads. |
70+
| `--download-timeout=<secs>` | Per-file timeout for downloading a linked entry upload. Overrides the `gk/gravitymigrate/import/download-timeout` filter (default 300). |
71+
| `--max-download-bytes=<n>` | Maximum bytes accepted for a single downloaded upload. Overrides the `gk/gravitymigrate/import/max-download-bytes` filter (default 100 MB). |
72+
| `--max-dump-file-size=<n>` | Maximum allowed size, in bytes, of the bundle's database dump. Overrides the `gk/gravitymigrate/import/max-dump-file-size` filter (default 500 MB). |
73+
| `--format=<format>` | Summary format: `table` (default) or `json`. |
74+
| `--yes` | Skip the confirmation prompt (import writes into Gravity Forms tables). |
75+
| `--porcelain` | Output only the newly created form IDs, one per line. |
76+
77+
```bash
78+
# Import a bundle
79+
wp gk migrate import bundle.zip --user=admin --yes
80+
81+
# Import only two of the bundle's forms, without downloading uploads
82+
wp gk migrate import bundle.zip --forms=2,5 --skip-uploads --user=admin --yes
83+
84+
# Raise the dump-size limit for one very large bundle
85+
wp gk migrate import big.zip --max-dump-file-size=1073741824 --user=admin --yes
86+
```
87+
88+
Entry file uploads are downloaded from the source site during import, so importing `uploads` pulls `entries` in with it. If a download fails because the source URL is unreachable, the entry keeps pointing at the source; re-export with `--public-url` set to an address the importing server can reach.
89+
90+
## `wp gk migrate inspect`
91+
92+
Prints a bundle's forms, data types, and source URL without importing it, and reports whether its upload URLs will resolve from this site and whether its database dump is within the size limit.
93+
94+
| Option | Description |
95+
| --- | --- |
96+
| `<zip>` | Path to the GravityMigrate export ZIP. Required. |
97+
| `--password=<password>` | ZIP password, if encrypted. |
98+
| `--format=<format>` | Output format: `table` (default) or `json`. |
99+
100+
```bash
101+
wp gk migrate inspect bundle.zip
102+
wp gk migrate inspect bundle.zip --format=json
103+
```
104+
105+
## `wp gk migrate status`
106+
107+
Reports current migration state: whether an import lock is held (and whether it is stale), whether a crashed import is saved, and whether an export left state to clean up.
108+
109+
| Option | Description |
110+
| --- | --- |
111+
| `--format=<format>` | Output format: `table` (default) or `json`. |
112+
113+
```bash
114+
wp gk migrate status
115+
wp gk migrate status --format=json
116+
```
117+
118+
## `wp gk migrate reset`
119+
120+
Clears stuck migration state: the temporary tables, the extracted import files, and the import and export progress options. Use it when an interrupted migration leaves a later one refused.
121+
122+
| Option | Description |
123+
| --- | --- |
124+
| `--yes` | Skip the confirmation prompt. |
125+
126+
```bash
127+
wp gk migrate reset --user=admin --yes
128+
```
129+
130+
## Data types
131+
132+
`--data` accepts a comma-separated list of these types, or `all`:
133+
134+
| Type | What it includes |
135+
| --- | --- |
136+
| `entries` | Form entries with their metadata and notes. |
137+
| `uploads` | Entry file uploads. Downloaded from the source during import, so it requires `entries`. |
138+
| `views` | GravityView Views. |
139+
| `posts` | The pages that embed your Views, and other connected posts. |
140+
| `revisions` | Form revision history. |
141+
| `addon_feeds` | Add-on feeds, for example GravityView and GravityCharts. |
142+
| `gravityflow` | Gravity Flow workflow activity, where present. |
143+
| `drafts` | Saved and continued draft submissions. |
144+
| `gf_settings` | Gravity Forms settings. |
145+
| `gk_settings` | GravityKit settings. |
146+
| `rest_api_keys` | Gravity Forms REST API keys. |
147+
148+
## Scripting
149+
150+
`--format=json` prints a machine-readable summary. `--porcelain` prints only the essential value: the ZIP path from `export`, or the newly created form IDs (one per line) from `import`. Together they let you chain a migration between two servers:
151+
152+
```bash
153+
#!/bin/bash
154+
set -e
155+
156+
# Export on the source site and capture just the ZIP path
157+
ZIP=$(wp gk migrate export --forms=all --data=all --porcelain --user=admin)
158+
159+
# Copy it to the destination and import it there
160+
scp "$ZIP" deploy@destination:/tmp/migration.zip
161+
ssh deploy@destination "wp gk migrate import /tmp/migration.zip --user=admin --yes --porcelain"
162+
```
163+
164+
## Tuning import safety limits
165+
166+
The import command caps download time, download size, and the bundle's database-dump size to protect the server. Each cap has a filter, and each filter has a matching `import` flag that overrides it for a single run:
167+
168+
| Filter | Flag | Default |
169+
| --- | --- | --- |
170+
| `gk/gravitymigrate/import/download-timeout` | `--download-timeout` | 300 seconds |
171+
| `gk/gravitymigrate/import/max-download-bytes` | `--max-download-bytes` | 100 MB |
172+
| `gk/gravitymigrate/import/max-dump-file-size` | `--max-dump-file-size` | 500 MB |
173+
174+
Set a filter to change the limit for every import on a site that legitimately migrates very large amounts of data:
175+
176+
```php
177+
add_filter( 'gk/gravitymigrate/import/max-dump-file-size', function () {
178+
return 1073741824; // 1 GB
179+
} );
180+
```
181+
182+
See the [Filters reference](/docs/gravitymigrate/filters/) for the full list, including `gk/gravitymigrate/export/row` and `gk/gravitymigrate/export/info` for reshaping exported data, and `gk/gravitymigrate/import/upload-url` for redirecting where a linked upload is downloaded from.
183+
184+
## Related
185+
186+
- [GravityMigrate filters](/docs/gravitymigrate/filters/)
187+
- [GravityMigrate actions](/docs/gravitymigrate/actions/)
188+
- [Migrating from the command line](https://www.gravitykit.com/docs/gravitymigrate/) (user guide)

0 commit comments

Comments
 (0)