docs: improve discussion of tarball to be imported by ddev import-files, fixes #5474 #5478
Conversation
|
Download the artifacts for this pull request:
See Testing a PR |
cmd/ddev/cmd/import-files.go
Outdated
| @@ -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, an archive of the Drupal 'sites/default/files' directory should contain only the contents of 'sites/default/files', not the 'files' directory. | |||
There was a problem hiding this comment.
how about adding:
For e.g. In other words, if your archive did contain the top-level "files" directory, then after import the result will be extracted to sites/default/files/files
There was a problem hiding this comment.
I guess IMO that's too much information. It's very specific about how to create the tarball.
There was a problem hiding this comment.
aside the detail about content and contents i've asked over in discord.
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 *not contain the files directory, just the contents of the files directory
the second sentence took me one or two times until i understood. i wonder if it would make sense to switch the order to what the goal is and then what situation should be avoided. i suppose the wording could still be improved
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 end up with a single `files` directory on unarchive containing all the contents.
And i wonder if it would make sense to shorten:
The easiest way to do this with the tar command is to cd into the directory and create the archive there
I would simply strike "the easiest way to do this.." and use something like
To export the files directory use:
or not sure what matt recommends as the common phrase for pointing at one or two lines of terminal input.
There was a problem hiding this comment.
Agreed, providing an example command will drive the point home. It will take the average person a few reads to completely understand this without an example. Keeping in mind that some automated backup processes do include the parent directory as part of the archive (as was in my case).
| $ 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 replaced with the | ||
| import assets specified here. |
There was a problem hiding this comment.
adding...
Importantly, all pre-existing files/folders in the target directory will be deleted as a part of this process.
There was a problem hiding this comment.
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
There was a problem hiding this comment.
Yes you are right. But some people (myself included) would appreciate banging the point home a bit. It is a destructive step after all.
rfay
force-pushed
the
20231030_import_files_docs
branch
from
afc7028
to
821141e
Compare
rfay
force-pushed
the
20231030_import_files_docs
branch
from
821141e
to
8827a16
Compare
|
Ready to go. |
The Issue
The user there did not understand that the tarball should not contain the top-level directory. I imagine this wasn't the first time.
How This PR Solves The Issue
Update docs and help.