### Install ascmhl for development Source: https://ascmhl.readthedocs.io/en/latest/README.html Clone the repository and install dependencies in an editable virtual environment. ```bash $ git clone https://github.com/ascmitc/mhl.git $ cd mhl $ python3 -m venv env $ source env/bin/activate $ pip3 install --editable . ``` -------------------------------- ### Verify ascmhl installation Source: https://ascmhl.readthedocs.io/en/latest/README.html Check if the tool is correctly installed by accessing the help menu. ```bash $ ascmhl --help ``` -------------------------------- ### Install Python 3 on macOS Source: https://ascmhl.readthedocs.io/en/latest/README.html Commands to install and configure Python 3 using Homebrew. ```bash $ brew install python3 $ brew postinstall python3 ``` -------------------------------- ### Install or upgrade ascmhl Source: https://ascmhl.readthedocs.io/en/latest/README.html Use pip to install or update the latest development version of the ascmhl tool. ```bash $ pip3 install --upgrade ascmhl ``` -------------------------------- ### Output file history with ascmhl info -sf Source: https://ascmhl.readthedocs.io/en/latest/README.html Use the -sf option with the info command to get detailed history for a specific file. The command reads history from the nearest ASC MHL history found in the specified path. ```bash $ ascmhl info -sf /path/to/file [-sf /path/to/other/file] [/root/path] ``` -------------------------------- ### Implementation details for create command (single files) Source: https://ascmhl.readthedocs.io/en/latest/README.html This details the process for the create command when using the -sf option for single files. It focuses on reading history, checking if files are recorded, hashing, and adding records to new generations. ```text read (recursive) mhl-history (mhllib) starting from root path for each file from input check if file is not recorded in `ascmhl` folder yet hash file add record for file to new generation (mhllib) add a new generation if necessary in appropriate `ascmhl` folder (mhllib) ``` -------------------------------- ### Implementation details for create command (file hierarchy) Source: https://ascmhl.readthedocs.io/en/latest/README.html This outlines the internal process of the create command when operating on a file hierarchy. It involves reading history, traversing folders, hashing files, comparing with existing records, and creating new generations. ```text read (recursive) mhl history (mhllib) traverse folder hash each file if `ascmhl` folder exists, compare hash (mhllib) on error (including mismatching hashes): print error continue add files to new generation if not present yet compare found files in file system with records in ascmhl folder and \ warn if files are missing that are recorded in the ascmhl folder create new generation(s) (mhllib) ``` -------------------------------- ### Info command implementation logic Source: https://ascmhl.readthedocs.io/en/latest/README.html The `info` command's implementation includes error checking for the ASCMHL folder, reading the history, and conditionally printing a summary or detailed file information based on provided options. ```plaintext error if no mhl folder found on root level read (recursive) mhl history (mhllib) if summary option: print summary if list option: for each file record print file info, hashes, etc. ``` -------------------------------- ### verify -pl Source: https://ascmhl.readthedocs.io/en/latest/README.html Verifies a folder structure against a provided packing list manifest. ```APIDOC ## verify -pl ### Description Verifies a folder structure using a given packing list manifest file. ### Parameters #### Path Parameters - **path/to/packing-list.mhl** (string) - Required - The path to the packing list manifest file. ``` -------------------------------- ### Info command usage Source: https://ascmhl.readthedocs.io/en/latest/README.html The `info` command provides an overview of the contents within an ASCMHL folder, displaying generation information and optionally a summary or a list of file records. ```bash $ ascmhl info [-s|-l] [-v] /path/to/ascmhl/ ``` -------------------------------- ### Verify Packing List Source: https://ascmhl.readthedocs.io/en/latest/README.html Use the `verify` command with the `-pl` option to validate a folder structure against a specified packing list manifest file. ```bash $ ascmhl verify -pl /path/to/packing-list.mhl ``` -------------------------------- ### Flatten command help output Source: https://ascmhl.readthedocs.io/en/latest/README.html Detailed options for the `flatten` command, including verbose output, skipping directory hashes, ignoring files, and specifying creator information like author name, email, phone, role, location, and comment. ```bash % ascmhl flatten --help Usage: ascmhl flatten [OPTIONS] ROOT_PATH DESTINATION_PATH Flatten an MHL history into one external manifest The flatten command iterates through the mhl-history, collects all known files and their hashes in multiple hash formats and writes them to a new mhl file outside of the iterated history. Options: -v, --verbose Verbose output -n, --no_directory_hashes Skip creation of directory hashes, only reference directories without hash -i, --ignore TEXT A single file pattern to ignore. -ii, --ignore_spec PATH A file containing multiple file patterns to ignore. --author_name TEXT Name value for the element in the element --author_email TEXT Email value for the element in the element --author_phone TEXT Phone value for the element in the element --author_role TEXT Role value for the element in the element --location TEXT Value for the element in the element --comment TEXT Value for the element in the element --help Show this message and exit. ``` -------------------------------- ### ASCMHL Info Command Source: https://ascmhl.readthedocs.io/en/latest/README.html The `info` command provides a summary of the contents within an ASCMHL folder. It can list generations with creator and process information, or provide a detailed list of file records including relative paths, sizes, and hashes. ```APIDOC ## POST /ascmhl/info ### Description Retrieves and displays information about the contents of an ASCMHL folder. It can provide a summary of recorded files and generations, or a detailed list of all file and folder records. ### Method POST ### Endpoint `/ascmhl/info` ### Parameters #### Query Parameters - **-s, --summary** (BOOLEAN) - Optional - Displays a summary of the information in the ASCMHL folder. - **-l, --list** (BOOLEAN) - Optional - Lists all file (and folder) records stored in the ASCMHL folder, including relative file paths, file size, and known file hashes. - **-v, --verbose** (BOOLEAN) - Optional - When used with the list option, includes creator info and process info for each generation. #### Path Parameters - **ASCHML_PATH** (PATH) - Required - The path to the specific ASCMHL folder. ### Request Example ```bash ascmhl info -v /path/to/ascmhl/ ``` ### Response #### Success Response (200) - **output** (string) - The information retrieved from the ASCMHL folder, formatted as text. #### Response Example ```json { "output": "Generation 1:\n Creator Info: { Location: Main Server, Comment: Initial import, Author: { Name: John Doe, Email: john.doe@example.com } }\n Process Info: ...\n" } ``` ``` -------------------------------- ### Flatten command usage Source: https://ascmhl.readthedocs.io/en/latest/README.html Use the flatten command to create a single manifest file from a directory hierarchy. Optional arguments allow for ignoring files and specifying creator information. ```bash $ ascmhl flatten [-i ignore pattern|-ii /path/to/ignore-file.txt] [creator-info options] /path/to/folder/ /destination/path/ ``` -------------------------------- ### ascmhl create command for file hierarchy Source: https://ascmhl.readthedocs.io/en/latest/README.html Use this command to traverse a folder hierarchy, hash all files (respecting ignore patterns), and compare them against existing records in the ascmhl folder. It records new files and detects missing ones. Creator-info options can be provided to add metadata. ```bash $ ascmhl create [-i ignore pattern|-ii /path/to/ignore-file.txt] [creator-info options] /path/to/folder/ ``` -------------------------------- ### ascmhl create command for single files Source: https://ascmhl.readthedocs.io/en/latest/README.html Use this command with the -sf option to record individual files within a managed hierarchy. A new generation is created in all ascmhl folders below the root path. This command requires an existing mhl-history; otherwise, an error is thrown. ```bash $ ascmhl create /path/to/root/folder -sf /path/to/single/file1 [-sf /path/to/single/file2 ..] ``` -------------------------------- ### Check XSD Schema for Directory File Source: https://ascmhl.readthedocs.io/en/latest/README.html Use the `xsd-schema-check` command with the `-df` option to validate an ASC MHL Directory file against the XSD schema. Provide the path to the directory file as the argument. ```bash $ ascmhl xsd-schema-check -df /path/to/ascmhl/ascmhl_chain.xml ``` -------------------------------- ### Verify Directory Hash Source: https://ascmhl.readthedocs.io/en/latest/README.html Use the `verify` command with the `-dh` option to create and compare a directory hash against historical data. The `-co` option calculates hashes without verification, and `-ro` further restricts it to only the root directory hash when used with `-co`. ```bash $ ascmhl verify -dh [-co [-ro]] /path/to/folder ``` -------------------------------- ### Diff command implementation logic Source: https://ascmhl.readthedocs.io/en/latest/README.html The `diff` command's logic involves error handling for missing ASCMHL folders, recursive reading of history, and comparison of file system contents with manifest records, exiting with a non-zero code on discrepancies. ```plaintext error if no mhl folder found on root level read (recursive) mhl history (mhllib) traverse folder on missing file: print error continue compare found files in file system with records in ascmhl folder \ and warn if files are missing that are recorded in the ascmhl folder end with exit !=0 if at least one of the files has failed, a file was \ missing, or new files have been found ``` -------------------------------- ### ASCMHL Flatten Command Source: https://ascmhl.readthedocs.io/en/latest/README.html The `flatten` command processes a file hierarchy, creating a single, flattened manifest file. It accepts a root path and a destination path, along with options for ignoring files and including creator information. ```APIDOC ## POST /ascmhl/flatten ### Description Flattens an MHL history into a single external manifest file. It iterates through the MHL history, collects all known files and their hashes, and writes them to a new MHL file outside the iterated history. ### Method POST ### Endpoint `/ascmhl/flatten` ### Parameters #### Query Parameters - **-i, --ignore** (TEXT) - Optional - A single file pattern to ignore. - **-ii, --ignore_spec** (PATH) - Optional - A file containing multiple file patterns to ignore. - **--author_name** (TEXT) - Optional - Name value for the `` element in the `` element. - **--author_email** (TEXT) - Optional - Email value for the `` element in the `` element (`--author_name` must also be set for this option). - **--author_phone** (TEXT) - Optional - Phone value for the `` element in the `` element (`--author_name` must also be set for this option). - **--author_role** (TEXT) - Optional - Role value for the `` element in the `` element (`--author_name` must also be set for this option). - **--location** (TEXT) - Optional - Value for the `` element in the `` element. - **--comment** (TEXT) - Optional - Value for the `` element in the `` element. - **-v, --verbose** (BOOLEAN) - Optional - Verbose output. - **-n, --no_directory_hashes** (BOOLEAN) - Optional - Skip creation of directory hashes, only reference directories without hash. #### Path Parameters - **ROOT_PATH** (PATH) - Required - The root path of the folder hierarchy to process. - **DESTINATION_PATH** (PATH) - Required - The destination path for the flattened manifest file. ### Request Example ```bash ascmhl flatten --author_name "John Doe" --location "Main Server" /path/to/folder/ /destination/path/ ``` ### Response #### Success Response (200) - **message** (string) - Confirmation of successful flattening. #### Response Example ```json { "message": "Manifest flattened successfully to /destination/path/" } ``` ``` -------------------------------- ### verify -dh Source: https://ascmhl.readthedocs.io/en/latest/README.html Verifies directory hashes by comparing calculated file hashes against existing history. ```APIDOC ## verify -dh ### Description Creates a directory hash by hashing files in a directory and compares it with the expected hash from the MHL history. ### Parameters #### Path Parameters - **path/to/folder** (string) - Required - The directory path to verify. #### Options - **-dh, --directory_hash** (flag) - Required - Enables directory hash verification. - **-co, --calculate_only** (flag) - Optional - Calculates and prints hashes without verifying against history. - **-ro, --root_only** (flag) - Optional - Calculates only the root directory hash (requires -co). ``` -------------------------------- ### Calculate directory hash with ascmhl info -dh Source: https://ascmhl.readthedocs.io/en/latest/README.html The info command with the -dh option calculates and prints the directory hash for a given ascmhl folder and subfolder. This can be used to verify folder structure integrity. ```bash $ ascmhl info -dh /path/to/ascmhl/ /path/to/sub/folder ``` -------------------------------- ### Diff command usage Source: https://ascmhl.readthedocs.io/en/latest/README.html Use the `diff` command to compare a folder structure against its ASCMHL records. It identifies new files not in the manifest and files missing from the file system. ```bash $ ascmhl diff /path/to/folder/ ``` -------------------------------- ### Hash Individual File Source: https://ascmhl.readthedocs.io/en/latest/README.html Use the `ascmhl-debug hash` command to generate and print a hash value for an individual file. Specify the desired hash algorithm using the `-h` or `--hash_format` option. ```bash $ ascmhl-debug hash --help Usage: ascmhl-debug hash [OPTIONS] FILE_PATH Create and print a hash value for a file Options: -h, --hash_format [md5|sha1|xxh128|xxh3|xxh64|c4] Algorithm [required] --help Show this message and exit. ``` -------------------------------- ### Check XSD Schema for Manifest File Source: https://ascmhl.readthedocs.io/en/latest/README.html Use the `xsd-schema-check` command to validate an ASC MHL Manifest file against its XML XSD schema. Ensure the `xsd` subfolder is accessible or specify the XSD file path using the `-xsd` option. ```bash $ ascmhl xsd-schema-check /path/to/ascmhl/XXXXX.mhl ``` -------------------------------- ### hash Source: https://ascmhl.readthedocs.io/en/latest/README.html Hashes an individual file using a specified algorithm. ```APIDOC ## hash ### Description Hashes an individual file with the given hash algorithm and prints the result. ### Parameters #### Path Parameters - **FILE_PATH** (string) - Required - The path to the file to hash. #### Options - **-h, --hash_format** (string) - Required - The algorithm to use (md5, sha1, xxh128, xxh3, xxh64, c4). ``` -------------------------------- ### Verify single file with ascmhl verify -sf Source: https://ascmhl.readthedocs.io/en/latest/README.html Use the -sf option with the verify command to check a single file's integrity against its recorded hash in the ascmhl history. It supports both relative and absolute file paths. ```bash $ ascmhl verify -sf /absolute/path/to/single/file ``` ```bash $ ascmhl verify -sf realtive/path/to/single/file ``` -------------------------------- ### Verify file hierarchy with ascmhl verify Source: https://ascmhl.readthedocs.io/en/latest/README.html The verify command checks the integrity of a file hierarchy by comparing file hashes against records in the ascmhl folder. It reports missing files or unregistered files and exits with a non-zero code on errors. ```bash $ ascmhl verify /path/to/folder/ ``` -------------------------------- ### xsd-schema-check Source: https://ascmhl.readthedocs.io/en/latest/README.html Validates ASC MHL manifest or directory files against XML XSD schemas. ```APIDOC ## xsd-schema-check ### Description Validates an ASC MHL Manifest or Directory file against the XML XSD. ### Parameters #### Path Parameters - **path/to/ascmhl/file** (string) - Required - The path to the .mhl or .xml file. #### Options - **-xsd, --xsd_file** (string) - Optional - Path to a local XSD file. - **-df** (flag) - Optional - Validates an ASC MHL Directory file instead of a manifest. ``` -------------------------------- ### ASCMHL Diff Command Source: https://ascmhl.readthedocs.io/en/latest/README.html The `diff` command compares a folder structure against its recorded ASCMHL history. It identifies new files not yet recorded and files that are missing from the file system but recorded in ASCMHL, exiting with a non-zero code if discrepancies are found. ```APIDOC ## POST /ascmhl/diff ### Description Compares a folder structure against its ASCMHL history to detect new or missing files. It does not create or verify hashes, providing a quick check for inconsistencies. Exits with a non-zero status code if any files are new, missing, or if recorded files are not found in the file system. ### Method POST ### Endpoint `/ascmhl/diff` ### Parameters #### Path Parameters - **ROOT_PATH** (PATH) - Required - The root path of the folder hierarchy to compare. ### Request Example ```bash ascmhl diff /path/to/folder/ ``` ### Response #### Success Response (200) - **message** (string) - Indicates that no discrepancies were found or lists the detected differences. #### Response Example ```json { "message": "No discrepancies found." } ``` ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.