scripts/blender-crawl/README.md

@@ -8,41 +8,69 @@ blender_crawl is a command line tools to purge orphan data of blend files via th
 
 ## Prerequisite
 In order to use this tool you need:
-- python3
+- Python 3.5+
 
 ## Run without Installation
-1. Clone repository the 
-2. run `cd blender_crawl` to enter directory
-3. Run program with `python blender_crawl /directory/`
+1. Clone this repository with `git clone https://projects.blender.org/studio/blender-studio-pipeline.git`
+2. Run `cd blender-studio-pipeline/scripts/blender-crawl` to enter directory
+3. Run program with `python blender_crawl /my-folder/` 
 
 ## Installation
 Download or clone this repository.
 This repository is a command line tool that can be installed with the python packaging manager. 
 This script does the following (follow this if you want to do this manually or on another platform):
 
-1. Clone repository
-2. Run `cd blender_crawl` to enter directory
+1. Clone this repository with `git clone https://projects.blender.org/studio/blender-studio-pipeline.git`
+2. Run `cd blender-studio-pipeline/scripts/blender-crawl` to enter directory
 3. Install with `python setup.py install`
-4. Run with `sudo python -m blender_crawl /directory/`
+4. Run with `sudo python -m blender_crawl /my-folder/`
 5. Get help with `sudo python3 -m blender_crawl -h`
 
 
 ## How to get started
-Run directly out of repo folder or follow above installation instructions.
+Run directly out of repo folder or follow above installation instructions. Give `blender_crawl` a path to a .blend file or a folder as first argument, The detected blend files will be opened in the background, the python script will be executed, and the file closes. If blender is not installed at the default location of your computer, you need to provide a blender executable using the --exec flag.
+
+| Command      | Description |
+| ----------- | ----------- |
+| --script| Path to blender python script(s) to execute inside .blend files during crawl.|
+| -r, --recursive| If provided in combination with a folder path will perform recursive crawl|
+| -f  --filter| Provide a string to filter the found .blend files|
+| -a, --ask| If provided there will be no confirmation prompt before running script on .blend files.|
+| -p, --purge| Run 'built-in function to purge data-blocks from all .blend files found in crawl.'.|
+| --exec| If provided user must provide blender executable path, OS default blender will not be used if found.|
+| -h, --help| show the above help message and exit|
+
+
+## Usage Examples
+### Basic Operation
+Prints the names of .blends in Current Directory 
+> `python -m blender_crawl ./`
+
+### Recursive
+Print the names of .blends Recursively
+> `python -m blender_crawl /my-folder/ --recursive`
+
+### Find
+Print only the names of .blends matching a provided string 
+> `python -m blender_crawl /my-folder/ --find string`
+
+### Purge
+Run default 'Purge' script on .blends in Current Directory 
+> `python -m blender_crawl /my-folder/ --purge`
+
+### Script
+Run custom script on all .blends in Current Directory 
+> `python -m blender_crawl /my-folder/ --script /my-directory/my-script.py`
+
+### Ask
+Ask/Prompt before script execution
+> `python -m blender_crawl /my-folder/ --script /my-directory/my-script.py --ask`
+
+### Exec
+Run with a custom blender executable
+> `python -m blender_crawl /my-folder/ --exec /path-to-blender-executable/blender`
+
+
 
-Give ``blender_crawl`` a path to a .blend file or a folder as first argument. 
-The detected blend files will be opened in the background, their orphan data will be
-purged recursively, the file gets saved and closed again. This will happen twice for each .blend file.
-
-If blender is not installed at the default location of your computer, you need to provide a blender executable
-using the --exec flag.
-
- -  --script        Path to blender python script(s) to execute inside .blend files during crawl. Execution is skipped if no script is provided
- -  -r, --recursive       If -R is provided in combination with a folder path will perform recursive crawl
- -  -f  --filter          Provide a string to filter the found .blend files
- -  -a, --ask             If --ask is provided there will be no confirmation prompt before running script on .blend files.
- -  -p, --purge           Run 'built-in function to purge data-blocks from all .blend files found in crawl.'.
- -  --exec EXEC           If --exec user must provide blender executable path, OS default blender will not be used if found.
-  -  -h, --help           show the above help message and exit
 
 

scripts/blender-crawl/blender_crawl/__main__.py

@@ -37,6 +37,14 @@ parser.add_argument(
 )
 
 parser.add_argument(
+    "-e",
+    "--exec",
+    help="If --exec user must provide blender executable path, OS default blender will not be used if found.",
+    type=str,
+)
+
+parser.add_argument(
+    "-s",
     "--script",
     help="Path to blender python script(s) to execute inside .blend files during crawl. Execution is skipped if no script is provided",
     nargs='+',
@@ -44,7 +52,7 @@ parser.add_argument(
 parser.add_argument(
     "-r",
     "--recursive",
-    help="If -R is provided in combination with a folder path will perform recursive crawl",
+    help="If -r is provided in combination with a folder path will perform recursive crawl",
     action="store_true",
 )
 
@@ -68,15 +76,12 @@ parser.add_argument(
     action="store_true",
 )
 
-parser.add_argument(
-    "--exec",
-    help="If --exec user must provide blender executable path, OS default blender will not be used if found.",
-    type=str,
-)
+
 
 
 def cancel_program(message: str):
     print(message)
+    print('Exiting blender_crawl.')
     sys.exit(0)
 
 
@@ -219,7 +224,7 @@ def main() -> int:
 
     if not scripts:
         cancel_program(
-            "No valid script files were found. Exiting program."
+            "No script files were provided to execute."
         )
         sys.exit(0)