Skip to content

Latest commit

 

History

History
132 lines (86 loc) · 6.96 KB

op_init.md

File metadata and controls

132 lines (86 loc) · 6.96 KB

Init Operation

The init operation is the starting point for using Perpetual with your project. It sets up the necessary configuration and directory structure required for Perpetual to function properly within your project environment.

Usage

To initialize a new Perpetual configuration for your project, run the following command from the root directory of your project:

Perpetual init [flags]

The init operation supports several command-line flags to customize its behavior:

  • -l <language>: Select the programming language for setting up default LLM prompts. This flag is required and must be provided with a valid language option.

  • -h: Display the help message, showing all available flags and their descriptions.

  • -v: Enable debug logging. This flag increases the verbosity of the operation's output, providing more detailed information about the initialization process.

  • -vv: Enable both debug and trace logging. This flag provides the highest level of verbosity, useful for troubleshooting or understanding the internal workings of the initialization process.

  • -c: Clean obsolete files and directories. When used, this flag removes deprecated configuration files and directories from the .perpetual directory.

Example Usage

Perpetual init -l go

This command initializes Perpetual for a Go project, setting up the appropriate configuration and prompt files.

Supported Languages

Perpetual currently supports the following programming languages and technologies:

  1. Go (go)
  2. .NET Framework (dotnetfw) - Includes C#, VB.NET, WPF.
  3. Bash (bash) - Note: Intended mostly for Linux use.
  4. Python 3 (python3)
  5. Visual Basic 6 (vb6) - Note: Not fully supported and may be removed in future releases.
  6. C (c)
  7. C++ (cpp)
  8. Arduino (arduino)

When using the -l flag, provide the language identifier as shown in parentheses above.

Details

The init operation performs several tasks to set up your project for use with Perpetual:

  1. Creates a .perpetual directory in your project root.
  2. Creates a global configuration directory if it doesn't exist.
  3. Generates default configuration files and prompts for the selected programming language.
  4. Creates a .gitignore file within the .perpetual directory to exclude specific Perpetual files from version control.
  5. Creates an example .env file to help configure environment variables for Perpetual and its LLM providers.
  6. Cleans obsolete configuration files and directories if the -c flag is used.

When run inside an already initialized project root, it will overwrite current config files and create missing ones.

Directory and File Structure

After running the init operation, the following structure is created:

<project_root>/
└── .perpetual/
    ├── .gitignore
    ├── .env.example
    ├── op_annotate.json
    ├── op_implement.json
    ├── op_doc.json
    ├── op_explain.json
    ├── op_report.json
    └── project.json

Customizable Files

Most files generated by the init operation can be customized to fine-tune Perpetual's behavior for your project:

  1. .env: This file is not created by default, but you can copy the .env.example file and modify it to set environment variables for configuring Perpetual and its LLM providers. The variables defined in these files are essential for proper operation, as they configure LLM providers, API keys, and other important settings.

    Perpetual looks for .env config files in multiple locations, loading them in the following order:

    • Project-wide configuration file from .perpetual directory inside project root (<project_root>/.perpetual/.env)
    • Global configuration file (e.g., ~/.config/Perpetual/.env on Linux, <User profile dir>\AppData\Roaming\Perpetual\.env on Windows)

    Options from project-wide config will take precedence over options from global config. Environment variables can also be set manually before launching Perpetual. In that case, they will take precedence over all other options.

  2. JSON Configuration Files for Specific Operations: These files (op_annotate.json, op_implement.json, op_doc.json, op_report.json) contain regular expressions, prompts, and other project-specific configurations used by Perpetual for source code file handling and processing. You can modify these to change how Perpetual interacts with your project files.

  3. project.json Config: This config file contains the following options:

    • files_to_md_code_mappings: Defines mappings between file types and corresponding markdown code block types. This helps Perpetual correctly identify and format code blocks in LLM requests and responses. Needed for some languages and project types (e.g., VB6) that use non-standard extensions for source code files.

    • project_files_blacklist: Specifies regex patterns for files that should be excluded from processing. Useful for filtering out specific sub-projects, tests, confidential files, etc.

    • project_files_whitelist: Defines regex patterns for files that are allowed to be processed by Perpetual. Ensures that only relevant files are included in operations.

    • project_test_files_blacklist: Contains regex patterns to exclude test files from processing. Helps in ignoring test suites and related files during operations.

These configuration files can be added to version control systems (VCS) like Git, allowing you to share and track changes to your Perpetual configuration across your development team.

Files Not Intended for User Modification

The following files and directories are automatically managed by Perpetual and should not be modified directly:

  1. .annotations.json: This file stores the source code annotations generated by Perpetual for your project files, used by other operations to understand your project structure. It is updated automatically during normal use. Use the annotate operation if you want to update them manually.

  2. .stash/: This directory is used by Perpetual to store source code backups during operations. Use the stash operation to manage these backups.

  3. .message_log.txt: This file contains logs of interactions between Perpetual and the LLM provider. It's used for debugging and tracking the AI's responses.

Cleaning Obsolete Files and Directories

When running the init operation with the -c flag, Perpetual will remove the following obsolete files and directories from the .perpetual directory (from previous versions):

  • Obsolete Files:

    • filename_embed_regexp.json
    • filename_tags_regexps.json
    • filename_tags.json
    • no_upload_comment_regexps.json
    • output_tags_regexps.json
    • project_files_blacklist.json
    • project_files_to_markdown_lang_mappings.json
    • project_files_whitelist.json
    • reasonings_tags_regexps.json
    • reasonings_tags.json

  • Obsolete Directories:

    • prompts