Branches and History

ActiveState projects support branching and version history, allowing you to experiment with different configurations while maintaining a stable main branch.

Understanding Branches

Branches allow you to:

  • Experiment with different package combinations
  • Test new language versions
  • Isolate development work
  • Maintain multiple variants of your project

Creating Branches

From the web interface:

  1. Go to your project’s page
  2. Click the Project Settings tab
  3. Click Branches on the left-hand side
  4. Click Add Child to create a new branch
  5. Give your branch a descriptive name
  6. Configure the branch settings

Working with Branches

Switch to a Different Branch

Via Web Interface:

  1. Go to your project’s page
  2. Click the Configuration tab
  3. Click the Branch dropdown
  4. Choose a branch

Via State Tool:

state switch <branch-name>

This command will only work if you are in the same directory as the project.

List Available Branches

state branch

Check Out a Specific Branch

state checkout --branch <branch-name> <org/project> <path>

For example:

state checkout --branch experimental ActiveState/Python3 ./my-project

Project History

Viewing History

Via Web Interface:

  1. Go to your project’s page
  2. Click the History tab
  3. View current and previous releases
  4. Select an earlier release to view its details

Via State Tool:

state history

Reverting to Previous Versions

Via Web Interface:

  1. Go to the History tab
  2. Select the commit you want to revert to
  3. Click Revert to this Commit
  4. Confirm your choice by clicking Revert

Via State Tool:

state revert <commit-id>

The commit id can be found in the web interface under the History tab.

Downloading Earlier Releases

  1. Go to your project’s page
  2. Click the History tab
  3. Select the commit you want to download
  4. Follow the download instructions for that specific commit

Commit Management

Creating Commits

When you make changes to your project (add/remove packages, change configurations), you create commits:

Via State Tool:

state push

This creates a commit with your local changes and syncs them to the Platform.

Viewing Commit Details

Each commit includes:

  • Timestamp of the change
  • User who made the change
  • Description of what changed
  • Package additions/removals
  • Build status

Commit Messages

When pushing changes, you can add descriptive commit messages:

state push --message "Added pandas for data analysis"

Best Practices

Branch Naming

  • Use descriptive names: feature/new-ml-packages, test/python39
  • Include purpose: experimental/, production/, testing/
  • Avoid spaces and special characters

Branch Strategy

  • Keep main branch stable for production use
  • Create feature branches for experiments
  • Test thoroughly before merging changes
  • Clean up unused branches regularly

History Management

  • Review history before making major changes
  • Use descriptive commit messages
  • Tag important releases for easy reference
  • Document breaking changes

Troubleshooting

Branch Not Showing

If a branch doesn’t appear:

  1. Refresh your web browser
  2. Run state pull to sync with remote changes
  3. Check your permissions for the project

Cannot Switch Branches

If you can’t switch branches:

  1. Ensure you have uncommitted local changes
  2. Push or discard local changes first
  3. Verify the branch exists and you have access

Lost Commit History

If commits seem missing:

  1. Check if you’re viewing the correct branch
  2. Verify your project permissions
  3. Contact support if data appears to be lost