Repository navigation
docs: add use cases, with the manual install the plugin replaces - #53
Merged
Merged
Conversation
- docs/use-cases.md and docs/zh-CN/use-cases.md: the five manual steps (download, unpack, a PATH line in ~/.bashrc) next to `vfox add`, `install` and `use`, then the situations the plugin is for: a machine with a hand-made install, projects on different versions, a team on one version, upgrading and going back, a beta in one terminal, a mirror, scripts and IDEs, ARM64 and OpenHarmony. - README.md and README_CN.md: a "Use cases" section that links to it. - versions.md and troubleshooting.md, both languages: vfox 1.0.13 adds `.vfox/` to an existing .gitignore, which versions.md denied, and a project's choice applies only in the directory that holds .vfox.toml, and only from the next prompt. The commands were run on Ubuntu 26.04.1 with vfox 1.0.13 and plugin 0.2.5.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a use-cases page that sets the plugin against installing Flutter by hand (download, unpack, a
PATHline in~/.bashrc) and goes through the situations it is for.Changes
docs/use-cases.mdanddocs/zh-CN/use-cases.md, nine scenarios: a new machine (the five manual steps next tovfox add/install/use), a machine with a hand-made install, projects on different versions, a team on one version, upgrading and going back, a beta in one terminal, a mirror, scripts and IDEs, ARM64 and OpenHarmony.README.mdandREADME_CN.md: a "Use cases" section, a few sentences and a link, as for every other subject.versions.mdsaid vfox does not add.vfox/to the project's.gitignore. vfox 1.0.13 does when the project has one (Added '.vfox/' to .gitignore), and creates none..vfox.toml, not in its subdirectories, and only from the next prompt, socd project && flutter runon one line still runs the previous directory's Flutter. Now inversions.mdand in the "flutteris a different Flutter thanvfox usesays" entry oftroubleshooting.md.No code changes.
What the page says about
~/.bashrcIt does not claim that
~/.bashrcis never touched. vfox still has to be hooked into the shell once (eval "$(vfox activate bash)"), andvfox usestops without the hook (vfox requires hook support. ...). What the plugin saves is everything about Flutter: nothing is added to, edited in or removed from~/.bashrcwhen you install, switch or uninstall, and a terminal that was already open picks the new choice up at its next prompt, where by hand each one has tosource ~/.bashrc.Verification
"Nothing in CI checks the docs, so run the commands you add", so they were run: Ubuntu 26.04.1 x64, vfox 1.0.13, plugin 0.2.5 from the registry, every run in a throwaway
HOME(env -i), never the real~/.vfox.flutter --version --no-version-checkruns.vfox install flutter@3.47.4downloaded the identical file: the SHA-256 it verifies against the index (5b45f0ce…) is whatsha256sumprinted for the manual download.vfox use --projectin two project directories (andvfox current flutterin a subdirectory),vfox execwithout the hook,~/.bashrcholding only the hook line afterwards, Flutter's settings in~/.config/flutterand the pub cache in~/.pub-cache, both outside the SDK.vfox use --globalat its next prompt, the session scope stays in its terminal,cdandflutteron one line use the previous directory'sPATH.stable/betaresolution, upgrade and rollback,vfox uninstall,vfox install --allfor a teammate, and a hand-made install next to vfox (the hook before and after theexport PATHline): against a fake mirror, the recipe indocs/development.md.What the runs turned up, and the page now avoids or explains:
flutter --version | head -n 1prints a 35-lineBroken pipestack trace on Flutter's very first run, when it also prints its telemetry notice. The examples usesed -n 1p.--no-version-check, the first run of an SDK older than the newest stable opens with the "A new version of Flutter is available! ... runflutter upgrade" box. The examples pass the flag, and the upgrade section points to the existing troubleshooting entry.vfox install --allinstalls but does not select: the teammate still runsvfox use --project. On a machine without the plugin, the first--allonly adds the plugin.For review
curlline on the page uses the Google host. It answers 200 with the sameContent-Lengthas the CFUG host, and its first 60 MB downloaded; the complete download went through CFUG.stable= 3.47.9 andbeta= 3.50.0-0.3.pre (2026-11-03, the same on Google's index and CFUG's) and vfox 1.0.13, dated like the other pages.troubleshooting.mdstill says a manual install earlier inPATHwins. On Ubuntu with Bash, vfox 1.0.13 put its directory first in both orders (the hook before or after the manualexportline), and the new page says so in its Ubuntu section. I left the existing sentence alone because macOS and Windows may differ. Narrow it if you agree.mainin it, to pick up Add a project OpenCode config allowing git push and PR create/comment #52'sopencode.jsonc. The repo only allows squash merges, so it does not reachmain.