Add a composefs backend

[cgwalters]

This adds a new off-by default feature to enable
a new composefs-native backend for bootc. This
is all still a live work in progress, but
we're landing this first tranche of work to help
avoid continual issues with rebasing.

Thanks to everyone who worked on it!

xref #1190

Co-authored-by: John Eckersberg [email protected]
Co-authored-by: Robert Sturla [email protected]
Co-authored-by: Colin Walters [email protected]
Signed-off-by: Pragyan Poudyal [email protected]

[gemini-code-assist]

Code Review

This pull request introduces composefs as a new backend, which is a significant and extensive change. The new code paths for installation, upgrades, switching, and rollbacks for composefs are well-structured.

My review has identified a few issues, including a potential bug with a hardcoded transport value and an assert! that could lead to a panic. I've also included some suggestions for improving code style and robustness. Given this is a work-in-progress, these findings are not unexpected. Overall, this is a solid foundation for the new composefs functionality.

[cgwalters]

I'm going to rebase this. In the interest of preserving history I've saved a copy of the branch as composefs-branch-20250804

[cgwalters]

OK at least this passes the existing tests.

[cgwalters]

I rebased 🏄 this again (and in the process reworked the composefs karg stuff to use the new kernel_cmdline &str APIs)

[cgwalters]

OK I'd like to land #1525 and then rebase again

[Johan-Liebert1]

Rebasing on main ends up with a bunch of conflicts again. I was thinking about moving all composefs related code to separate files/crate to minimize conflicts

[cgwalters]

Notes from meeting

• Need to rebase (should squash most commits again)
• Considering merging mostly as is with lots of followups
• Gate code based on feature flag
• Trust in automated tests, but also do a lot of manual testing post-merge to be sure it doesn't break the ostree path

[cgwalters]

@jeckersb before rebasing this would you mind also saving the existing branch? We've done that for the last few rebases

[jeckersb]

Worth noting that I didn't do any of the squashing during the rebase, but at least with it clean we can easily decide which ones to squash out.

[Johan-Liebert1]

I'll be going ahead and rebasing again in prep for #1560

[jeckersb]

rebased this again (saved the old one at composefs-backend-2025-09-03) to fix a conflict and pick up #1581

[cgwalters]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces significant new functionality for composefs support, including installation, upgrades, switching, and rollbacks. The changes are extensive, touching many parts of the codebase to accommodate composefs as an alternative to the existing ostree backend. New modules, data structures, and logic have been added to handle composefs-native systems.

The review has identified a few important issues. There's a high-severity bug where a hardcoded "docker" transport is used, which will prevent switching to images from other transports. Another high-severity issue is that a crucial finalization step (install_finalize) is skipped for composefs installations, potentially leaving them in an inconsistent state. Additionally, there are some medium-severity concerns regarding robustness against non-UTF8 paths and inconsistent use of std::fs versus cap_std for filesystem operations.

Overall, this is a great step towards composefs integration, and addressing these points will improve the correctness and robustness of the new functionality.

[Johan-Liebert1]

Needs another rebase. Maybe one after #1598 lands, which is required for #1573

[Johan-Liebert1]

Rebased again. Only one conflict found

<<<<<<< HEAD
etc-merge = { path = "../etc-merge" }
=======
bootc-initramfs-setup = { path = "../initramfs" }
>>>>>>> 023be101 (composefs/install: Copy /etc contents to state)

Accepted both, and saved previous branch to composefs-backend-10-09-2025

[cgwalters]

OK I rebased this, the conflict was from #1603 mainly. The resolutions were pretty straightforward.

[cgwalters]

Previous branch is backed up at https://github.com/bootc-dev/bootc/tree/composefs-backend-2025-09-12

[Johan-Liebert1]

Rebased again. Saved the previous branch to composefs-backend-15-09-2025

Conflict found

<<<<<<< HEAD
=======
    #[clap(hide(true))]
    #[cfg(feature = "docgen")]
    Man(ManOpts),
    #[cfg(feature = "composefs-backend")]
    ComposefsFinalizeStaged,
>>>>>>> a7185978 (Add a composefs backend)

resolved to

    #[cfg(feature = "composefs-backend")]
    ComposefsFinalizeStaged,

[Johan-Liebert1]

Weird, the make-validate issue should've been fixed by #1606, but that change is neither present in the rebased branch nor in the branch before the rebase. It is present in https://github.com/bootc-dev/bootc/tree/composefs-backend-2025-09-12 though. Probably something went wrong during last Friday's rebase @cgwalters?

[cgwalters]

Hmm...ugh. Looking...

[cgwalters]

OK after some auditing I think what happened is pretty simple, I probably forgot to git fetch and so rebased an old version of the branch. Pushed the 3 missing commits here.

[cgwalters]

Since I created this PR, I can't approve it; @jeckersb can you do so?

[jeckersb]

🥳