en-US/about_Whiskey_MergeFile_Task.help.txt
|
TOPIC
about_Whiskey_MergeFile_Task SUMMARY Merges multiple files into a single, new file. DESCRIPTION The `MergeFile` task takes one or more source files and merges them together into a destination file. Pass the list of source files to merge to the `Path` property (wildcards are supported). Pass the path to the destination file where the files should be merged to the `DestinationPath` property. The destination file will be created if it doesn't exist. If the destination file already exists, its contents will be preserved. To clear the contents of the destination file before merging in other files, set the `Clear` property to `true`. By default, the source files are left in place. If you'd like to delete the source files as they are merged into the destination file, set the `DeleteSourceFiles` property to `true`. Files are concatenated as-is. If you want to ensure each file is separated from other files, set either the `TextSeparator` property to a string to use to separate each file, or the `BinarySeparator` property to an array of bytes (i.e. numbers between 0 and 255). After merging each file, the task adds the separator. If both `TextSeparator` and `BinarySeparator` are given, the task (and your build) will fail. PROPERTY * `Path` (*mandatory*): a list of one or more paths to merge. Wildcards are supported. Must be to files under the current build root. * `DestinationPath (*mandatory*): the path to the file into which the files will be merged. Must be under the build root. Will be created if it doesn't exist. Existing contents will be preserved. Set the `Clear` property to `true` to remove any existing contents before merging any files. * `DeleteSourceFiles`: if set to `true`, will delete each source file after is is merged into the destination file. The default value is `false`. * `TextSeparator`: a string of text to use to separate each file's content when merging. We recommend `$(NewLine)` when merging text files. * `BinarySeparator`: a list of bytes to use to separate each file's content when merging. Each item in the list must be a number between 0 and 255. * `Clear`: by default, the task leaves the destination file's content in place. To clear the destination file before merging files, set this property to `true`. * `Exclude`: files to exclude from the merge. Wildcards supported. Each pattern is checked against each file's full path. You may use either slash as a directory separator character. EXAMPLES ## Example 1 Build: - MergeFile: Path: *.txt DestinationPath: .output\Merged.txt This example demonstrates how to combine files into a single file. All `*.txt` file in the current build root will be merged as-is into the file `.output\Merged.txt`. ## Example 2 Build: - MergeFile: Path: *.txt DestinationPath: .output\merged.txt TextSeparator: "$(NewLine)" This example demonstrates how to customize any text to put between each file while merging. In this case, the current operating system's newline character (or characters) is added. ## Example 3 Build: - MergeFile: Path: *.txt DestinationPath: .output\all.txt BinarySeparator: - 28 This example demonstrates how to use a binary separator when merging files. In this, the ASCII file separator character is used. ## Example 4 Build: - MergeFile: Path: *.txt DestinationPath: .output\all.txt DeleteSourceFiles: true This example demonstrates how to delete each source file after merging it into the destination file. ## Example 5 Build: - MergeFile: Path: - Whiskey\Functions\*.ps1 - Whiskey\Tasks\*.ps1 DestinationPath: Whiskey\Whiskey.psm1 DeleteSourceFiles: true TextSeparator: "$(NewLine)$(NewLine)" This example demonstrates how to optimize PowerShell modules that store each function in their own file. It merges each file into a single file. This makes importing modules with many functions much faster. ## Example 6 Build: - MergeFile: Path: - Carbon\Functions\*.ps1 Exclude: - "*-Iis*" - "*\\Initalize-Lcm.ps1" DestinationPath: Carbon\Functions\Functions.ps1 DeleteSourceFile: true TextSeparator: "$(NewLine)$(NewLine)" Demonstrates how to exclude files from being merged. In this case, all files with "*-Iis*" in their full path will be excluded, as well as files whose paths end with "\\Initialize-Lcm.ps1". |