apt-ostree/.notes/rpm-ostree-cli-analysis.md

rpm-ostree CLI Analysis for apt-ostree Mirroring

Date: December 19, 2024
Goal: Mirror all rpm-ostree CLI commands for identical user experience

Current rpm-ostree Commands

Based on rpm-ostree --help output:

Core Package Management

• ✅ install - Overlay additional packages (apt-ostree: install)
• ✅ uninstall - Remove overlayed additional packages (apt-ostree: remove)
• ✅ upgrade - Perform a system upgrade (apt-ostree: upgrade)
• ✅ search - Search for packages (apt-ostree: search)

Deployment Management

• ✅ status - Get the version of the booted system (apt-ostree: status)
• ✅ rollback - Revert to the previously booted tree (apt-ostree: rollback)
• deploy - Deploy a specific commit (apt-ostree: checkout - needs enhancement)
• rebase - Switch to a different tree (apt-ostree: checkout - needs enhancement)

Transaction Management

• cancel - Cancel an active transaction
• cleanup - Clear cached/pending data
• reset - Remove all mutations

System Configuration

• apply-live - Apply pending deployment changes to booted deployment
• kargs - Query or modify kernel arguments
• override - Manage base package overrides
• reload - Reload configuration

Initramfs Management

• initramfs - Enable or disable local initramfs regeneration
• initramfs-etc - Add files to the initramfs

Repository Management

• refresh-md - Generate apt repo metadata (instead of RPM)
• compose - Commands to compose a tree

Database Operations

• db - Commands to query the APT database (instead of RPM)

Advanced Features

• usroverlay - Apply a transient overlayfs to /usr

Implementation Priority

High Priority (Core Functionality)

1. deploy - Essential for deployment management
2. rebase - Essential for switching between trees
3. cancel - Important for transaction safety
4. cleanup - Important for system maintenance
5. reset - Important for system recovery

Medium Priority (System Management)

1. apply-live - Advanced deployment feature
2. kargs - Kernel argument management
3. override - Package override management
4. reload - Configuration management

Low Priority (Advanced Features)

1. initramfs - Initramfs management
2. initramfs-etc - Initramfs file management
3. refresh-md - Repository metadata generation
4. compose - Tree composition
5. db - Database querying
6. usroverlay - Transient overlayfs

Key Differences to Consider

Package Search

• rpm-ostree: Has its own package search implementation
• apt-ostree: Currently relies on apt search
• Action: Implement our own package search like rpm-ostree

Database Operations

• rpm-ostree: Uses RPM database
• apt-ostree: Uses APT database
• Action: Implement APT-specific database operations

Repository Metadata

• rpm-ostree: Generates RPM repository metadata
• apt-ostree: Should generate APT repository metadata
• Action: Implement APT-specific metadata generation

Implementation Notes

Command Mapping

• uninstall → remove (already implemented)
• deploy → checkout (needs enhancement)
• rebase → checkout (needs enhancement)

APT-Specific Adaptations

• Use APT database instead of RPM database
• Use APT repository metadata instead of RPM metadata
• Implement APT-specific package search
• Use APT package format instead of RPM

User Experience

• Maintain identical command syntax and behavior
• Provide same error messages and help text
• Ensure same output format where possible
• Keep same command-line options and flags

Next Steps

1. Analyze rpm-ostree source code to understand command implementations
2. Prioritize command implementation based on user needs
3. Implement high-priority commands first
4. Test command compatibility with rpm-ostree
5. Update documentation to reflect complete CLI mirroring

References

• rpm-ostree source code: https://github.com/coreos/rpm-ostree
• rpm-ostree documentation: https://coreos.github.io/rpm-ostree/
• rpm-ostree CLI reference: rpm-ostree --help