Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs: improve discussion of tarball to be imported by ddev import-files, fixes #5474 #5478

Merged
merged 3 commits into from
Nov 22, 2023
Merged

docs: improve discussion of tarball to be imported by ddev import-files, fixes #5474 #5478

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1fdb752
docs: improve discussion of tarball to be imported by ddev import-fil…
rfay Oct 30, 2023
8827a16
Implement feedback from @rebelmusic and @rpkoller
rfay Nov 2, 2023
bc0a10b
incorporate comments on PR
rfay Nov 22, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
2 changes: 2 additions & 0 deletions .spellcheckwordlist.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -610,6 +610,7 @@ system32
systemctl
systemd
tableplus
tar
tasklist
tcp
tcpview
Expand Down Expand Up @@ -698,6 +699,7 @@ you
your
yoursite
zcompdump
zip
zsh
zshrc
zxf
4 changes: 3 additions & 1 deletion cmd/ddev/cmd/import-files.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,8 @@ func NewImportFileCmd() *cobra.Command {
The destination directories can be configured in your project's config.yaml
under the upload_dirs key. If no custom upload directory is defined, the app
type's default upload directory will be used.

If importing a Tar or Zip archive, the archive should contain only the *contents* of the top-level target directory. For example in a Drupal site with files at sites/default/files, the archive should only contain the contents of that 'files' directory. You shouldn't have a single 'files' directory in the archive containing all the contents.
`),
Example: heredoc.DocI2S(`
ddev import-files --source=/path/to/files.tar.gz
Expand Down Expand Up @@ -119,7 +121,7 @@ func importFilesRun(app *ddevapp.DdevApp, uploadDir, sourcePath, extractPath str

const importPathPrompt = `Provide the path to the source directory or archive you wish to import.`

const importPathWarn = `Please note: if the destination directory exists, it will be replaced with the
const importPathWarn = `Please note: if the destination directory exists, it will be emptied and replaced with the
import assets specified here.`

// promptForFileSource prompts the user for the path to the source file.
Expand Down
25 changes: 18 additions & 7 deletions docs/content/users/usage/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,8 +58,8 @@

To import static file assets for a project, such as uploaded images and documents, use the command [`ddev import-files`](../usage/commands.md#import-files). This command will prompt you to specify the location of your import asset, then import the assets into the project’s upload directory. To define a custom upload directory, set the [`upload_dirs`](../configuration/config.md#upload_dirs) config option. If no custom upload directory is defined, the default will be used:

* For Backdrop projects, this is the `files`.
* For Drupal projects, these are the `sites/default/files` and `../private` directories.
* For Backdrop projects, this is `files`.
* For Drupal projects, this is `sites/default/files`.
* For Magento 1 projects, this is the `media` directory.
* For Magento 2 projects, this is the `pub/media` directory.
* For Shopware projects, this is the `media` directory.
Expand All @@ -69,17 +69,28 @@
Other project types need a custom configuration to be able to use this command.

```bash
ddev import-files
Provide the path to the directory or archive you wish to import. Please note, if the destination directory exists, it will be replaced with the import assets specified here.
Import path:
~/Downloads/files.tar.gz
Successfully imported files for drupal8
$ ddev import-files
Provide the path to the source directory or archive you wish to import.
Please note: if the destination directory exists, it will be emptied and replaced with the
import assets specified here.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

adding...

Importantly, all pre-existing files/folders in the target directory will be deleted as a part of this process.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's actually what it already says isn't it?

if the destination directory exists, it will be replaced with the import assets specified here

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes you are right. But some people (myself included) would appreciate banging the point home a bit. It is a destructive step after all.

Path to file(s): ~/workspace/d10/.tarballs/files.tgz
You provided an archive. Do you want to extract from a specific path in your
archive? You may leave this blank if you wish to use the full archive contents.
Archive extraction path:
Successfully imported files for d10
```

`ddev import-files` supports the following file types: `.tar`, `.tar.gz`, `.tar.xz`, `.tar.bz2`, `.tgz`, or `.zip`.

It can also import a directory containing static assets.

If using a Tar or Zip archive, the archive should contain *only the files inside the files directory*. For example in a Drupal site with files at `sites/default/files`, the archive should only contain the contents of the `files` directory; it should not contain a single `files` directory. To do this with the `tar` command, `cd` into the directory and create the archive there. An example Tar file creation is:

Check failure on line 87 in docs/content/users/usage/cli.md

View workflow job for this annotation

GitHub Actions / Docs check (spellcheck, markdownlint, textlint) 

[textlint] reported by reviewdog 🐶
Incorrect usage of the term: “Zip”, use “ZIP” instead (terminology)

Raw Output:
/home/runner/work/ddev/ddev/docs/content/users/usage/cli.md:87:19: error: Incorrect usage of the term: “Zip”, use “ZIP” instead (terminology) (eslint.rules.terminology)

```bash
cd web/sites/default/files
tar -czf ~/Downloads/files.tgz .
```

If you want to use `import-files` without answering prompts, use the `--source` or `-s` flag to provide the path to the import asset. If you’re importing an archive, and wish to specify the path within the archive to extract, you can use the `--extract-path` flag in conjunction with the `--source` flag. Example:

`ddev import-files --source=/tmp/files.tgz`
Expand Down
2 changes: 1 addition & 1 deletion docs/content/users/usage/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -715,7 +715,7 @@

## `import-files`

Pull the uploaded files directory of an existing project to the default [public upload directory](../usage/cli.md#ddev-import-files) of your project.
Pull the uploaded files directory of an existing project to the default public upload directory of your project. More usage information and a description of the Tar or Zip archive is in the [usage section](../usage/cli.md#ddev-import-files).

Check failure on line 718 in docs/content/users/usage/commands.md

View workflow job for this annotation

GitHub Actions / Docs check (spellcheck, markdownlint, textlint) 

[textlint] reported by reviewdog 🐶
Incorrect usage of the term: “Zip”, use “ZIP” instead (terminology)

Raw Output:
/home/runner/work/ddev/ddev/docs/content/users/usage/commands.md:718:169: error: Incorrect usage of the term: “Zip”, use “ZIP” instead (terminology) (eslint.rules.terminology)

Flags:

Expand Down