Organize and Manage Projects

Learn how to organize and manage multiple ActiveState projects effectively on your system.

Need help deploying projects? See the Checkout and Activate guide for complete deployment instructions including checkout methods, activation strategies, and working with multiple projects simultaneously.

This guide covers:

Finding Your Projects

To see all projects currently checked out on your system:

state projects

This command displays:

  • Project names and organizations
  • Local checkout paths (where activestate.yaml files are located)
  • Runtime cache locations (where binaries are stored)
  • Current activation status

Example output:

Organization/Project           Local Checkout Path              Cache Path
example/python-project        /home/user/projects/python      /home/user/.cache/activestate/...
example/data-analysis         /home/user/analysis             /home/user/.cache/activestate/...

Organizing Project Locations

Organize your projects logically to make them easier to find and manage:

By language:

~/activestate-projects/
├── python/
│   ├── web-app/
│   ├── data-science/
│   └── automation/
├── perl/
│   ├── legacy-system/
│   └── tools/
└── ruby/
    └── rails-app/

By purpose:

~/projects/
├── production/
│   ├── web-backend/
│   └── api-service/
├── development/
│   ├── experimental-features/
│   └── testing/
└── personal/
    └── side-projects/

By team or organization:

~/work/
├── team-alpha/
│   ├── project-a/
│   └── project-b/
├── team-beta/
│   └── project-c/
└── shared/
    └── common-tools/

Best Practices for Organization

  1. Use consistent paths - Choose a structure and stick to it
  2. Descriptive folder names - Make the purpose clear from the name
  3. Avoid deep nesting - Keep structures 2-3 levels deep maximum
  4. Separate by environment - Keep production, staging, and development separate
  5. Document your structure - Keep a README explaining your organization system

Project Naming Conventions

On the Platform

When creating projects on the ActiveState Platform:

Good project names:

  • python-web-api - Clear purpose and language
  • data-pipeline-prod - Indicates environment
  • ml-training-env - Descriptive and concise

Avoid:

  • project1, test, tmp - Not descriptive
  • my-awesome-super-cool-project-v2-final - Too long
  • Project!@#$ - Special characters can cause issues

Local Folder Names

Match or clearly relate to your Platform project names:

state checkout myOrg/python-web-api ~/projects/python-web-api

Managing Project Lifecycle

Active Projects

Projects you’re currently working on:

  1. Regular updates - Run state pull frequently to stay synced
  2. Commit changes - Use state push after making local changes
  3. Monitor status - Check state projects to verify activation
  4. Branch management - Use branches for experimental work

Archived Projects

For projects you’re not actively using but want to keep:

  1. Move to archive folder - Separate from active projects

    mkdir -p ~/projects/archive
mv ~/projects/old-project ~/projects/archive/

  2. Document the state - Add README with last known good commit

  3. Keep activestate.yaml - Allows quick reactivation if needed

  4. Remove from active list - But keep for reference

Completed Projects

For finished projects:

  1. Final push - Ensure all changes are saved to Platform
  2. Tag final version - Use Platform history to mark completion
  3. Document outcomes - Add notes about final state
  4. Clean up locally - See Cleaning up projects

Cleaning Up Projects

Remove Local Checkout

To remove a checked-out project from your system:

  1. Navigate out of the project directory

  2. Delete the project folder:

    rm -rf ~/projects/old-project

  3. Verify removal:

    state projects

The project will no longer appear in the list.

Deleting the local checkout does NOT delete the project from the ActiveState Platform. Your project remains safe on the Platform and can be checked out again anytime.

Clear Runtime Cache

The State Tool caches runtime files to improve performance. To clear cached runtimes:

state clean cache

This removes cached runtime files but preserves your project configurations.

Complete Cleanup

To remove all State Tool data including configurations:

state clean uninstall --all

This removes ALL local State Tool data. Use with caution.

Working with Multiple Projects

For information on working with multiple projects simultaneously, including:

  • Running multiple projects in separate shells
  • Setting and managing default runtimes
  • Avoiding conflicts between projects
  • Switching between projects efficiently

See the Checkout and Activate guide.

Best Practices Summary

Organization

  • ✅ Use a consistent directory structure
  • ✅ Name projects descriptively
  • ✅ Separate active, archived, and completed projects
  • ✅ Document your organization system

Maintenance

  • ✅ Regular state pull to stay current
  • ✅ Commit changes with state push
  • ✅ Clean up unused projects periodically
  • ✅ Keep track of project purposes and owners

Collaboration

  • ✅ Use meaningful project names
  • ✅ Share organization conventions with team
  • ✅ Document project purposes
  • ✅ Keep projects synced with Platform