diff --git a/cmd/convmv/convmv.go b/cmd/convmv/convmv.go index 5e4071f81..baf678a34 100644 --- a/cmd/convmv/convmv.go +++ b/cmd/convmv/convmv.go @@ -34,17 +34,15 @@ var commandDefinition = &cobra.Command{ Long: strings.ReplaceAll(` convmv supports advanced path name transformations for converting and renaming files and directories by applying prefixes, suffixes, and other alterations. -`+transform.Help()+` - -Multiple transformations can be used in sequence, applied in the order they are specified on the command line. +`+transform.Help()+`Multiple transformations can be used in sequence, applied in the order they are specified on the command line. The ¡--name-transform¡ flag is also available in ¡sync¡, ¡copy¡, and ¡move¡. -## Files vs Directories ## +## Files vs Directories By default ¡--name-transform¡ will only apply to file names. The means only the leaf file name will be transformed. However some of the transforms would be better applied to the whole path or just directories. -To choose which which part of the file path is affected some tags can be added to the ¡--name-transform¡ +To choose which which part of the file path is affected some tags can be added to the ¡--name-transform¡. | Tag | Effect | |------|------| @@ -54,11 +52,11 @@ To choose which which part of the file path is affected some tags can be added t This is used by adding the tag into the transform name like this: ¡--name-transform file,prefix=ABC¡ or ¡--name-transform dir,prefix=DEF¡. -For some conversions using all is more likely to be useful, for example ¡--name-transform all,nfc¡ +For some conversions using all is more likely to be useful, for example ¡--name-transform all,nfc¡. Note that ¡--name-transform¡ may not add path separators ¡/¡ to the name. This will cause an error. -## Ordering and Conflicts ## +## Ordering and Conflicts * Transformations will be applied in the order specified by the user. * If the ¡file¡ tag is in use (the default) then only the leaf name of files will be transformed. @@ -73,19 +71,19 @@ user, allowing for intentional use cases (e.g., trimming one prefix before addin * Users should be aware that certain combinations may lead to unexpected results and should verify transformations using ¡--dry-run¡ before execution. -## Race Conditions and Non-Deterministic Behavior ## +## Race Conditions and Non-Deterministic Behavior Some transformations, such as ¡replace=old:new¡, may introduce conflicts where multiple source files map to the same destination name. This can lead to race conditions when performing concurrent transfers. It is up to the user to anticipate these. * If two files from the source are transformed into the same name at the destination, the final state may be non-deterministic. * Running rclone check after a sync using such transformations may erroneously report missing or differing files due to overwritten results. -* To minimize risks, users should: - * Carefully review transformations that may introduce conflicts. - * Use ¡--dry-run¡ to inspect changes before executing a sync (but keep in mind that it won't show the effect of non-deterministic transformations). - * Avoid transformations that cause multiple distinct source files to map to the same destination name. - * Consider disabling concurrency with ¡--transfers=1¡ if necessary. - * Certain transformations (e.g. ¡prefix¡) will have a multiplying effect every time they are used. Avoid these when using ¡bisync¡. +To minimize risks, users should: +* Carefully review transformations that may introduce conflicts. +* Use ¡--dry-run¡ to inspect changes before executing a sync (but keep in mind that it won't show the effect of non-deterministic transformations). +* Avoid transformations that cause multiple distinct source files to map to the same destination name. +* Consider disabling concurrency with ¡--transfers=1¡ if necessary. +* Certain transformations (e.g. ¡prefix¡) will have a multiplying effect every time they are used. Avoid these when using ¡bisync¡. `, "¡", "`"), Annotations: map[string]string{ diff --git a/lib/transform/gen_help.go b/lib/transform/gen_help.go index e0cc0ddd5..292c51d4e 100644 --- a/lib/transform/gen_help.go +++ b/lib/transform/gen_help.go @@ -51,7 +51,7 @@ var commandList = []commands{ {command: "--name-transform nfd", description: "Converts the file name to NFD Unicode normalization form."}, {command: "--name-transform nfkc", description: "Converts the file name to NFKC Unicode normalization form."}, {command: "--name-transform nfkd", description: "Converts the file name to NFKD Unicode normalization form."}, - {command: "--name-transform command=/path/to/my/programfile names.", description: "Executes an external program to transform"}, + {command: "--name-transform command=/path/to/my/programfile names.", description: "Executes an external program to transform."}, } var examples = []example{ @@ -106,7 +106,7 @@ func commandTable() string { for _, c := range commandList { s += fmt.Sprintf("\n| `%s` | %s |", c.command, c.description) } - s += "\n\n\n" + s += "\n\n" return s } @@ -116,23 +116,23 @@ func SprintList() string { var charmaps transform.CharmapChoices s := commandTable() - s += fmt.Sprintln("Conversion modes: \n```") + s += "Conversion modes:\n\n```\n" for _, v := range algos.Choices() { - s += fmt.Sprintln(v + " ") + s += v + "\n" } - s += fmt.Sprintln("```") + s += "```\n\n" - s += fmt.Sprintln("Char maps: \n```") + s += "Char maps:\n\n```\n" for _, v := range charmaps.Choices() { - s += fmt.Sprintln(v + " ") + s += v + "\n" } - s += fmt.Sprintln("```") + s += "```\n\n" - s += fmt.Sprintln("Encoding masks: \n```") - for _, v := range strings.Split(encoder.ValidStrings(), ",") { - s += fmt.Sprintln(v + " ") + s += "Encoding masks:\n\n```\n" + for _, v := range strings.Split(encoder.ValidStrings(), ", ") { + s += v + "\n" } - s += fmt.Sprintln("```") + s += "```\n\n" s += sprintExamples()