feat: add floxhub environments page #385
Conversation
github-actions
bot
added
the
documentation
zmitchell
force-pushed
the
push-pyxstmokpvnr
branch
from
0a70aca to
bb3603e
Compare
There was a problem hiding this comment.
unrelated, but i thought we had fixed the trailing newline
There was a problem hiding this comment.
Ah, chonker is still on 1.7.5
| ## Operations on FloxHub environments | ||
|
|
||
| CLI commands that interact with FloxHub environments will primarily operate on the cached copy of the environment. | ||
| This allows you to use FloxHub environments offline if a cached copy exists. |
There was a problem hiding this comment.
I'm still not sure if "offline use" is really the primary differentiator.
"Offline" is not qualified enough, ie. anything requiring resolution naturally still requires you to be "online".
Its also kind of what you'd expect assuming consistent behaviour between Floxhub envs and local envs.
Being able to do stuff offline or air-gapped is also a pretty specific usecase focusing on which feels somewhat narrow.
| This allows you to use FloxHub environments offline if a cached copy exists. | |
| This means changes to the environment can be tested locally without affecting other users of the environment. | |
| It also allows you to activate FloxHub environments without an active connection to FloxHub. |
There was a problem hiding this comment.
we are aiming to allow people to use Flox offline (plane, train, etc when no wifi etc is available), right? I thought this was highlighting why you would want a local copy...? Perhaps not all our (relevant) commands though have been updated to work when offline?
There was a problem hiding this comment.
I think the primary differentiator is
I no longer have to do a fetch from FloxHub for every command that uses a
-rflag because I can make use of a copy of the environment that already exists on my machine.
One use for that is working offline. Another use is testing out local changes.
I would put money on opinions and use cases for this feature being (in order):
- I don't care what's happening behind the scenes, but
flox activate -ris much faster now. - If I'm on a plane or the subway I can
flox activate -rwithout internet access. - Let me test out some local changes before pushing.
| - A cached copy transparently managed by Flox | ||
| - Fetch this manually via `flox pull --reference <owner>/<name>` |
There was a problem hiding this comment.
suggestion nonblocking: I think we should add that we do an implicit pull for any command that uses --reference
There was a problem hiding this comment.
Is that a pull that moves the local copy forward?
|
|
||
| ## Getting a FloxHub environment | ||
|
|
||
| Once you've pushed an environment to FloxHub, you can then use the [`flox pull`][flox-pull] command to fetch a copy of the environment to your machine. |
There was a problem hiding this comment.
Once you've pushed an environment to FloxHub, you can then use the [
flox pull][flox-pull] command to fetch a copy of the environment to your machine.
As you have just described pushing it to FloxHub, it doesn't make much sense to pull it right back to the same place. Perhaps you could say
Once you've pushed an environment to FloxHub, you or others can then use the [
flox pull][flox-pull] command to fetch (or update) a copy of the environment to your/their machine.
Or something more to emphasise different people, different machines...?
Also, do we want to start using the flox pull -r instead of just flox pull or do we plan to do that later? I know both will work now but in the future when you do flox init -r, flox pull should error and recommend flox pull -r, right? And what would happen now for those who didn't create the env but pulled it to their machine without having the directory? Wouldn't it error as flox pull currently assumes flox pull -d behaviour?
There was a problem hiding this comment.
Also, do we want to start using the
flox pull -rinstead of justflox pullor do we plan to do that later?
I'm just referring to generic flox pull command here, not a specific usage of it. I don't understand having a timeline attached to that.
in the future when you do
flox init -r,flox pullshould error and recommendflox pull -r, right?
I haven't heard anything about that being an error, and I don't think it should be an error. To me, flox init -r creates an upstream copy on FloxHub and a local copy. At that point it's like any other FloxHub environment, so I don't see why pulling it into a directory (which is what flox pull <env> does) would be an error.
And what would happen now for those who didn't create the env but pulled it to their machine without having the directory?
I'm not sure what this is asking. What do you mean "without having the directory"?
There was a problem hiding this comment.
As I understand it:
when you do a flox pull -r to get an env from floxhub you don't have on your machine yet, no directory is needed and the manifest, etc is magically / transparently managed by Flox (the user doesn't need to worry or know where the .flox stuff in located locally).
when you do a flox pull which I understand is the same as flox pull -d, the manifest, etc is located in the .flox folder in the pre-defined/pre-created directory. But if they haven't created that directory, and they run flox pull will this then error? Otherwise how does flox pull know where to put/find the .flox stuff?
|
|
||
| <!-- markdownlint-disable MD007 --> | ||
| - A cached copy transparently managed by Flox | ||
| - Fetch this manually via `flox pull --reference <owner>/<name>` |
There was a problem hiding this comment.
--reference
can we also include the -r option here?
| - Materialized into a user-specified directory | ||
| - Created via `flox pull <owner>/<name>` | ||
| - Placed into the current directory by default | ||
| - Specify a different directory with the `-d/--directory` flag |
There was a problem hiding this comment.
should we explicitly note the default assumption here when -d isn't included?
There was a problem hiding this comment.
I'm not sure what you're asking. There's bullets for both the default case (current directory) and the specific directory case (-d).
There was a problem hiding this comment.
I am saying doesn't flox pull <owner>/<name> assume flox pull / -d
(ie if the -d flag isn't given it is assuming the current directory by default)
| - Specify a different directory with the `-d/--directory` flag | ||
| <!-- markdownlint-enable MD007 --> | ||
|
|
||
| This cached copy is created and managed by the Flox CLI. |
There was a problem hiding this comment.
which copy are we now referring to? you note 2 copies above but then start giving more info on the "cache" one (undefined) so it isn't obviously clear.
There was a problem hiding this comment.
There are two options above:
- Cached copy
- Materialized copy
So when I say "This cached copy" I'm referring to the first of the two options, which says "cached copy".
There was a problem hiding this comment.
ok, this wasn't clear to me and it isn't clear to me how that relates to the local vs upstream just defined immediately before this. I just think the definition and transition needs to be improved for a user to follow. And it isn't clear to me which copy the last sentence in this section pertains to - both the cached and the materialised copies?
| This cached copy is created and managed by the Flox CLI. | ||
| Additionally, the Flox CLI will automatically fetch updates from FloxHub (without automatically applying them) so that the locally cached copy of the environment has up to date knowledge of the upstream state. | ||
|
|
||
| The upstream state of the environment can be fetched manually via the `flox pull (-r | --reference) <owner>/<name>` command. |
There was a problem hiding this comment.
seems like we are interweaving info for the 2 versions which is confusing.
And I don't know which the "cached" copy is and not previously defined. "Upstream" and "local" were...
Side note - this also makes me ask why we aren't warning re updates for both?
There was a problem hiding this comment.
The "cached copy" is defined above in the bulleted section.
I'm not sure what this means: "this also makes me ask why we aren't warning re updates for both?"
There was a problem hiding this comment.
for both a) floxhub managed envs and b) project envs.
The way it is written is that this only applies to the cached copy.
|
|
||
| ## Operations on FloxHub environments | ||
|
|
||
| CLI commands that interact with FloxHub environments will primarily operate on the cached copy of the environment. |
There was a problem hiding this comment.
again the term "cached" - I am assuming as I read this you are meaning the "local" copy? But does it matter if a directory-based version or if a managed floxhub version? Sorry, I am now getting really confused with the terms and types and therefore which command(s) apply. For now I am assuming you are only referring here to the local copy of the managed (floxhub) type of env.
| Generation: 2 | ||
| Timestamp: 2025-12-15 21:04:27 UTC | ||
|
|
||
| Remote: |
There was a problem hiding this comment.
is "remote" the correct word to use here? I would think "FloxHub" would be clearer? Or "source of truth" ;-)
There was a problem hiding this comment.
No, "remote" isn't the correct word anymore. @mkenigs
| To stop using this environment, type 'exit' | ||
| ``` | ||
|
|
||
| The `flox activate` command succeeds, but the message indicates that you need to run either a `flox pull` or `flox push` command (`flox push` in this case since you have local changes): |
There was a problem hiding this comment.
perhaps add "to synchronise the 2 copies" in this sentence?
|
|
||
| - The copy that lives on FloxHub, which is the source of truth | ||
| - The copy that exists locally for a given user on a given machine | ||
|
|
There was a problem hiding this comment.
so revisiting after a full pas through. It seems we have 2 types of copies (upstream vs local) but we also have 2 different use cases (one transparently managed by Flox and no directory is needed, and one created and controlled in a directory via .flox or github, etc). I am thinking these 2 types should also have terms defined here that can then easily be referenced below. Or does the type created and controlled in a directory not fall under the "FloxHub env" type and therefore it is the next section that needs more clarity as we are starting to mix and match?
There was a problem hiding this comment.
We don't really have an external name for a FloxHub environment that has been pulled into a directory. I agree that we should have a name for it since it's a thing that exists. I'd rather not call it out until we know how to talk about it.
There was a problem hiding this comment.
Internally we refer to these as "managed" environments, but I did a pass over the documentation yesterday and we haven't used it anywhere in the documentation.
There was a problem hiding this comment.
We don't really have an external name for a FloxHub environment that has been pulled into a directory. I agree that we should have a name for it since it's a thing that exists. I'd rather not call it out until we know how to talk about it.
yeah, so far though isn't being referred to as a materialised copy in this doc?
|
|
||
| In order to view the _history_ of generations (which displays how the "live" generation has evolved over time, any rollbacks that occurred, etc), you use [`flox generations history`][gen-hist]. | ||
| Again, the `--upstream` flag will show you the history as understood by the upstream copy. | ||
|
|
There was a problem hiding this comment.
love this.
My only thought though is what happens if I pulled the env into a directory as per the 2nd option under "getting a floxhub env"? Does all this in this section still work as described?
There was a problem hiding this comment.
I think this is how to think about it:
When pulled into a directory,
flox install, etc (no-r) act as if you had passed-r
There was a problem hiding this comment.
I don't understand that comment unfortunately (sorry!) and so I don't understand if the generations and history commands would still work on not.
|
|
||
| In order to see the list of packages in the local copy of a FloxHub environment you use the [`flox list -r`][flox-list] command. | ||
| Add the `--upstream` flag to see the packages in the upstream copy of the FloxHub environment. | ||
|
|
There was a problem hiding this comment.
same thought as for the "Generations" section.
|
|
||
| Activating a FloxHub environment is done via the [`flox activate -r`][flox-activate] command. | ||
| This will activate the current state of the local copy of the FloxHub environment, which may not be up to date with the upstream copy. | ||
| To activate the environment as it exists upstream, run `flox pull -r <owner>/<name>` before running `flox activate`. |
There was a problem hiding this comment.
before running flox activate or flox activate -r? Will both work so it doesn't matter?
There was a problem hiding this comment.
Before running flox activate -r. Fixed.
install -r operates on local copy, not upstream directly
Removed incorrect claim that updates are automatically picked up
We stopped using current a while ago but never updated the docs
We've renamed the `Change Log` tab on FloxHub to `History`
Some of the distinctions betweeen when to use `-r` vs `-d` have changed
No description provided.