Improve `--pattern` documentation with additional examples

[tomfaltesek]

Resource Provider
Azure Storage Blobs

Description of Work Requested
I'd like to suggest expanding the documentation around the --pattern parameter. Specifically, there is a lack of examples for common globbing scenarios. The tools for powerful patterns seem to be available, but the exact syntax required to achieve certain outcomes is not obvious.

I opened this SO question about making an exclusion pattern for the az storage blob delete-batch command. You can find other folks having trouble with different scenarios.

I'm sure you can think of many example patterns that one might want to use, but here's a quick brain dump:

• Delete everything except for one specific directory
• Delete everything except for multiple specific directories
• Delete everything in a specific nested directory
• Delete all but one particular blob in a specific nested directory
• Delete everything from a specific directory that matches an extension (*.txt)
• Delete everything from a specific directory that matches multiple extensions (*.txt or *.html)
• Delete everything from a specific directory that does NOT match an extension (*.txt)
• Delete everything from a specific directory that does NOT match multiple extensions (*.txt or *.html)

Providing such examples in the documentation will help others to form the correct patterns for their needs.

[Juliehzl]

Tom Faltesek (@tomfaltesek) Thanks for your suggestion. I think you can try our new az storage remove command with --exclude flag, which is in preview now. Wait for you feedback😊

[tomfaltesek]

Thanks for the reply, Zunli Hu (@Juliehzl). The az storage remove command with the --exclude flag looks like it should work fine. Although, that command was added in version 2.0.70 of the Azure CLI and my Azure DevOps build agent currently has version 2.0.68.

Fortunately, I can use the answer to this SO question to exclude directories with the existing Azure CLI commands.

Regardless of the new az storage remove command, consumers may want more detailed documentation on the --pattern parameter. Not only is it available for the az storage blob delete-batch, but it can also be used in the az storage blob download-batch and az storage blob upload-batch.

[bacongobbler]

Adding a few more use cases to the list for after using az storage blob upload-batch --pattern:

• upload everything with a particular file extension (*.txt)
• upload everything with a particular file extension somewhere in the name (*.tar.gz, *.tar.gz.sha256)
• upload everything that matches one of many file extensions (*.txt, *.md)

1) and 2) are quite simple to implement (*.txt and *.txt*), but I haven't found any concrete examples demonstrating 3).

In particular, I'd love to read more on the expected behaviour and limitations of the [seq] pattern matcher. There's very little information available on how it should be used. I've looked everywhere (including by looking through several test cases in azure-cli itself), but didn't find any concrete examples other than what was provided in the SO answer shared above.

[bacongobbler]

update: looks like the pattern matcher comes from fnmatch, a python library that provides UNIX-style file pattern match sequences. The documentation doesn't appear to demonstrate much information on how the pattern matcher works, however you can drop into a python shell to play around with some patterns to see what it would provide as a regular expression.

><> python
Python 2.7.15+ (default, Oct  7 2019, 17:39:04) 
[GCC 7.4.0] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import fnmatch
>>> fnmatch.translate("*")
'.*\\Z(?ms)'