doc: remove --expose-gc flag from CLI documentation

[dario-piotrowicz]

The CLI documentation for --expose-gc has been added in #53078

However it's removal was requested in #53078 (comment) (since this is not something users should generally rely on), but the documentation wasn't fully removed from the PR before it landed.

So I believe that the flag being documented might have been an oversight.

Original context: #58878 (comment)

---

Note: I'm trying to figure out here if --expose-gc should or not be documented in the CLI documentation, and if it should be I would be inclined to also include it in the manpage for consistency 🤔

---

Note: I wanted to also mention that the flag is also included in the allowed v8 options and the useful v8 options
(meaning that even after removing the cli flag section some references to it, for advanced users, will still be present in the document)

[jakecastelli]

This one feels similar to the --expose-internals CLI flag which exists but not documented.

We use --expose-internals exclusively in Core for various testing purposes but outside of core development it is not encouraged.

[juanarbol]

However it's removal was requested in #53078 (comment) (since this is not something users should generally rely on), but the documentation wasn't fully removed from the PR before it landed.

The docs are pretty much the usage at runtime and what is does (the idea behind documenting stuff), which is inherit from V8. I did not introduced the flag per se, I just added it to the CLI available options, I don't think we should remove the documentation, when the documentation is just showing the usage and that it is part of the available CLI options.

I don't think it is the right thing to do, each flag should be documented; but feel free to land this; I'm not blocking anything.

[dario-piotrowicz]

However it's removal was requested in #53078 (comment) (since this is not something users should generally rely on), but the documentation wasn't fully removed from the PR before it landed.

The docs are pretty much the usage at runtime and what is does (the idea behind documenting stuff), which is inherit from V8. I did not introduced the flag per se, I just added it to the CLI available options, I don't think we should remove the documentation, when the documentation is just showing the usage and that it is part of the available CLI options.

I don't think it is the right thing to do, each flag should be documented; but feel free to land this; I'm not blocking anything.

Hey @juanarbol 🙂

Thanks a lot for chipping in 🙏

I see your point but I also see that we have various v8 flags that are not documented (and some that are) so I do believe that there's unclarity on this 🤔

I think that ideally we should only document the flags that node specifically implements, the V8 flags that it supports should be just listed (as they are here: available v8 options)

And the nodejs docs should simply then refer to the the V8 official documentation regarding the flags that it supports...

The problem being that I can't seem to find any official V8 documentation regarding the supported flags... any idea if there is one? 🫤

[juanarbol]

The V8 team is not that good documenting flags as well. From my personal experience, I just have to look at this file https://github.com/v8/v8/blob/b5b7de9cc158c9d4dc038841e5935c49e4764d7e/src/flags/flag-definitions.h#L2594

Again, this is not a blocker, but I don't see this adding any actual value but making things a bit more confusing. I know Node.js has a mess w/ node options and CLI options, but removing docs is not the answer IMHO.

However it's removal was requested in #53078 (comment) (since this is not something users should generally rely on), but the documentation wasn't fully removed from the PR before it landed.

The requested removal of the docs was something about V8 I wrote about. Not the CLI entry and usage.

[dario-piotrowicz]

The V8 team is not that good documenting flags as well. From my personal experience, I just have to look at this file https://github.com/v8/v8/blob/b5b7de9cc158c9d4dc038841e5935c49e4764d7e/src/flags/flag-definitions.h#L2594

I see, that's a useful link to know about, thank you very much 🙏

Again, this is not a blocker, but I don't see this adding any actual value but making things a bit more confusing. I know Node.js has a mess w/ node options and CLI options, but removing docs is not the answer IMHO.

Thanks a lot, I really appreciate the input 🙂 , personally I see the argument both ways, if we think that this is a foot gun and not something people should be using then it makes sense to me that we don't publicly document it, on the other hand if it is something that node provides it does make sense to document that...

I would have hoped for more people to chip in here 😅 , hopefully someone else will tipping the scale in either direction 🤞

[aduh95]

Should we move it to https://nodejs.org/api/cli.html#useful-v8-options?

[joyeecheung]

I think moving it to the useful V8 options section would be the right move - it's not up to Node.js to decide how it behaves, so it shouldn't be documented like other Node.js options.

FWIW the existing documentation is somewhat misleading - it would make you think that this triggers a blocking GC that's supposed to clean up all remaining unreachable objects, but that's not the case and even has been the cause of some of our flakes. That function only triggers one GC, and one single GC does not guarantee to clean up everything especially when there are weak references or ephemeron pairs in the graph.

[jakecastelli]

+1 on Joyee's suggestion

[aduh95]

It's already in Useful V8 Options section:

node/doc/api/cli.md

Line 4255 in 4f4077a

### `--expose-gc`

[nodejs-github-bot]

Commit Queue failed

- Loading data for nodejs/node/pull/58909
✔  Done loading data for nodejs/node/pull/58909
----------------------------------- PR info ------------------------------------
Title      doc: remove `--expose-gc` flag from CLI documentation (#58909)
Author     Dario Piotrowicz <dario.piotrowicz@gmail.com> (@dario-piotrowicz)
Branch     dario-piotrowicz:dario/remove-expose-gc-from-cli -> nodejs:main
Labels     doc, cli, author ready
Commits    1
 - doc: remove `--expose-gc` flag from CLI documentation
Committers 1
 - Dario Piotrowicz <dario.piotrowicz@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/58909
Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/58909
Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
--------------------------------------------------------------------------------
   ℹ  This PR was created on Mon, 30 Jun 2025 22:24:25 GMT
   ✔  Approvals: 2
   ✔  - Jake Yuesong Li (@jakecastelli): https://github.com/nodejs/node/pull/58909#pullrequestreview-2975252574
   ✔  - Antoine du Hamel (@aduh95) (TSC): https://github.com/nodejs/node/pull/58909#pullrequestreview-4323953013
   ✔  Last GitHub CI successful
   ℹ  Green GitHub CI is sufficient
--------------------------------------------------------------------------------
   ✔  No git cherry-pick in progress
   ✔  No git am in progress
   ✔  No git rebase in progress
--------------------------------------------------------------------------------
- Bringing origin/main up to date...
From https://github.com/nodejs/node
 * branch                  main       -> FETCH_HEAD
✔  origin/main is now up-to-date
- Downloading patch for 58909
From https://github.com/nodejs/node
 * branch                  refs/pull/58909/merge -> FETCH_HEAD
✔  Fetched commits as 4f4077a299f1..154d819b56da
--------------------------------------------------------------------------------
Auto-merging doc/api/cli.md
[main c106c49288] doc: remove `--expose-gc` flag from CLI documentation
 Author: Dario Piotrowicz <dario.piotrowicz@gmail.com>
 Date: Mon Jun 30 23:02:40 2025 +0100
 1 file changed, 19 deletions(-)
   ✔  Patches applied
--------------------------------------------------------------------------------
--------------------------------- New Message ----------------------------------
doc: remove `--expose-gc` flag from CLI documentation
PR-URL: #58909

Reviewed-By: Jake Yuesong Li <jake.yuesong@gmail.com>

Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
[main 7fd1141b43] doc: remove --expose-gc flag from CLI documentation

Author: Dario Piotrowicz <dario.piotrowicz@gmail.com>

Date: Mon Jun 30 23:02:40 2025 +0100

1 file changed, 19 deletions(-)

✖  7fd1141b43e8aa6158de6b4785b6e51960a8b4d6

✔  0:0      no Assisted-by metadata                   assisted-by-is-trailer

✔  0:0      no Co-authored-by metadata                co-authored-by-is-trailer

✔  0:0      skipping fixes-url                        fixes-url

✔  0:0      blank line after title                    line-after-title

✔  0:0      line-lengths are valid                    line-length

✔  0:0      metadata is at end of message             metadata-end

✔  1:8      PR-URL is valid.                          pr-url

✔  0:0      reviewers are valid                       reviewers

✖  0:0      Commit must have a "Signed-off-by" trailer signed-off-by

✔  0:0      valid subsystems                          subsystem

✔  0:0      Title is formatted correctly.             title-format

⚠  0:50     Title should be <= 50 columns.            title-length
ℹ  Please fix the commit message and try again.

Please manually ammend the commit message, by running

git commit --amend

Once commit message is fixed, finish the landing command running

git node land --continue

https://github.com/nodejs/node/actions/runs/26131088912