You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@hugegraph.apache.org by "bitflicker64 (via GitHub)" <gi...@apache.org> on 2026/09/05 18:45:18 UTC
[PR] doc(toolchain): sync tools with master [hugegraph-doc]
bitflicker64 opened a new pull request, #475:
URL: https://github.com/apache/hugegraph-doc/pull/475
## Purpose of the PR
Sync the hugegraph-tools docs (en + cn) with hugegraph-toolchain master (3b385c3d).
The pages had drifted from the CLI: they documented a global option that is not registered, missed one global option and several sub-command options, listed options on the auth commands that do not exist there, and carried several wrong defaults. The usage block was also missing three graph sub-commands and both auth sub-commands.
| Page | What was wrong | What changed | Source on master |
|------|----------------|--------------|------------------|
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | `--protocol` listed as a global option, but it is never registered on the main command | Removed it; replaced with a note that the protocol comes from the `--url` scheme | hugegraph-tools/src/main/java/org/apache/hugegraph/cmd/HugeGraphCommand.java:62-86, base/ToolClient.java:51 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | `--throw-mode` global option not documented | Added it with its `false` default | cmd/SubCommands.java:753-759 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | `--trust-store-file` / `--trust-store-password` had no stated constraint; `--user` / `--password` pairing not stated | Added a note that the truststore options require an https `--url`, and that user and password must both be set or both omitted | base/ToolClient.java:51-70, cmd/HugeGraphCommand.java:411-414 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | `JAVA_HOME` and `JAVA_OPTIONS` not mentioned | Added a line describing both, including the computed `-Xmx` | hugegraph-tools/assembly/bin/hugegraph:47-52, 136-143 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | graph-create `--name` default given as `hugegraph`, and `--file` marked required | Default corrected to `g`; `--file` is optional and its content is sent as the graph config | cmd/SubCommands.java:377-382, 831-837 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | graph-clone `--name` default given as `hugegraph`, and `--clone-graph-name` missing | Default corrected to `g`; added `--clone-graph-name` with default `hugegraph` | cmd/SubCommands.java:396-402 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | Nothing said about the timeout floor on the graph sub-commands | Added a note that graph-create, graph-clone, graph-clear and graph-drop raise `--timeout` to at least 300 seconds | cmd/HugeGraphCommand.java:55-56, 268, 277, 297, 306 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | Section 3.4 heading omitted task-cancel and task-clear | Heading updated to list all five task sub-commands | cmd/SubCommands.java:69-73 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | task-list `--status` had no value list; `--limit` had no positivity note; task-cancel `--task-id` not marked required | Added the eight legal statuses, the positive-value rule, and the required marker | manager/TasksManager.java:31-34, cmd/SubCommands.java:888-909, 1247-1257 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | `--huge-types` list omitted the `schema` value | Added `schema` and what it expands to for backup, restore and migrate | cmd/SubCommands.java:761-773, 1039-1054 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | `--log` default given as the current directory | Corrected to `./logs` | cmd/SubCommands.java:638-640 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | `--thread-num` / `-T` missing from backup, restore, migrate and dump | Added with the `Math.min(10, Math.max(4, CPUs / 2))` default | cmd/SubCommands.java:642-646, base/RetryManager.java:33-34 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | `--split-size` had no minimum | Added the 1048576 (1M) minimum on backup, migrate and dump | manager/BackupManager.java:110-113 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | backup `--label` described only as applying to vertex/edge backups | Restated the enforced rule: `--huge-types` must name exactly one type, vertex or edge | manager/BackupManager.java:98-105 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | Nothing said about the backup timeout floor | Added a note that a `--timeout` below 120 seconds is raised to 120 for backup and for the backup step of migrate | manager/BackupManager.java:67, cmd/HugeGraphCommand.java:188-190, 220-222 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | restore did not say which graph modes it requires | Added a note that the graph must be in RESTORING or MERGING | cmd/HugeGraphCommand.java:200-203, hugegraph-client/src/main/java/org/apache/hugegraph/structure/constant/GraphMode.java:85-87 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | migrate `--graph-mode` had no default and no note about the mode swap | Added the RESTORING default and the switch-back behaviour | cmd/SubCommands.java:310-314, cmd/HugeGraphCommand.java:236-255 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | schedule-backup `--interval` had no default, and the crontab behaviour was undocumented | Added the `"0 0 * * *"` default plus a note on the crontab entry, the backup path, the retention and the relative-path rule | cmd/SubCommands.java:102-119, assembly/bin/schedule-backup.sh:29-134, assembly/bin/backup.sh:29-37 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | dump `--directory` default given as the current directory | Corrected to `./{graphName}` locally and `{fs.default.name}/{graphName}` on HDFS | cmd/SubCommands.java:632-636, base/LocalDirectory.java:138-142, base/HdfsDirectory.java:176-190 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | auth-backup / auth-restore listed `--log` and `--thread-num`, which they do not accept, and gave `-d` as a short form of `--directory` | Removed both options and the `-d` short form; corrected the directory default to `./auth-backup-restore` | cmd/SubCommands.java:912-926 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | auth `--types` did not state the belong/access dependencies; `--init-password` condition was vague | Added the dependency rules and the exact condition on `--types` containing `user` | cmd/SubCommands.java:1003-1016, 1088-1097, manager/AuthBackupRestoreManager.java:228-233 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | deploy / start-all `-v` had no value list; clear did not describe its guards; the default download prefix was not named | Added the version-map values, the running-process and prompt guards, and the default prefix | assembly/bin/version-map.yaml:19-42, assembly/bin/deploy.sh:22, 76-80, assembly/bin/clear.sh:64-93 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | Nothing said that the install sub-commands bypass the Java CLI | Added a note that deploy, start-all, clear and stop-all are handed to the shell scripts, so the global options do not apply | assembly/bin/hugegraph:54-75 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | Usage block was missing graph-create, graph-clone, graph-drop, auth-backup and auth-restore, and carried stale option text and a typo | Refreshed the block against the current parameter definitions | cmd/SubCommands.java:59-93, 122-125, 215-218, 763-773 |
| content/{en,cn}/docs/quickstart/toolchain/hugegraph-tools.md | Build output described as `hugegraph-tools-${version}.tar.gz`, and the release-package layout was not given | Corrected to `apache-hugegraph-tools-${version}.tar.gz` plus the unpacked directory, and added the path to the tools directory inside the toolchain package | hugegraph-tools/pom.xml:34-38, 181-215, hugegraph-tools/assembly/descriptor/assembly.xml:18-48, hugegraph-dist/pom.xml:33-60 |
| content/{en,cn}/docs/guides/backup-restore.md | Server address given as `http://127.0.0.1` | Corrected to `http://127.0.0.1:8080`, the actual `--url` default | cmd/SubCommands.java:694-697 |
| content/{en,cn}/docs/guides/backup-restore.md | Said backup works in "all three graph modes" and listed three modes for graph-mode-get | There are four modes; backup does not check the mode at all, while restore requires RESTORING or MERGING | hugegraph-client/src/main/java/org/apache/hugegraph/structure/constant/GraphMode.java:24-87, cmd/HugeGraphCommand.java:187-203 |
Scope note: only the hugegraph-tools parts of the backup/restore guide were touched.
Paths in the "Source on master" column are relative to `hugegraph-tools/` unless stated otherwise.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] doc(toolchain): sync tools with master [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #475:
URL: https://github.com/apache/hugegraph-doc/pull/475#discussion_r3942868074
##########
content/en/docs/quickstart/toolchain/hugegraph-tools.md:
##########
@@ -196,60 +207,61 @@ Another way is to set the environment variable in the bin/hugegraph script:
- --target-trust-store-file, access the truststore file used by the target graph
- --target-trust-store-password, the password to access the truststore used by the target map
- --directory or -d, during the migration process, the directory where the schema or data of the source graph is stored. For a local directory, the default is './{graphName}'; for HDFS, the default is '{fs.default.name}/ {graphName}'
- - --huge-types or -t, the data types to be migrated, separated by commas, the optional value is 'all' or a combination of one or more [vertex, edge, vertex_label, edge_label, property_key, index_label], 'all' Represents all 6 types, namely vertices, edges and all schemas
- - --log or -l, specify the log directory, the default is the current directory
+ - --huge-types or -t, the data types to be migrated, separated by commas, the optional value is 'all' or a combination of one or more [vertex, edge, vertex_label, edge_label, property_key, index_label], 'all' Represents all 6 types, namely vertices, edges and all schemas, 'schema' represents the 4 schema types [vertex_label, edge_label, property_key, index_label]
+ - --log or -l, specify the log directory, the default is ./logs
- --retry, specify the number of failed retries, the default is 3
- - --split-size or -s, specify the size of the vertex or edge block when backing up the source graph during the migration process, the default is 1048576
+ - --thread-num or -T, the number of threads to use, default is Math.min(10, Math.max(4, CPUs / 2))
+ - --split-size or -s, specify the size of the vertex or edge block when backing up the source graph during the migration process, the default is 1048576, and it must be at least 1048576 (1M)
- -D, use the mode of -Dkey=value to specify dynamic parameters, which are used to specify HDFS configuration items when the data needs to be backed up to HDFS during the migration process, for example: -Dfs.default.name=hdfs://localhost: 9000
- - --graph-mode or -m, the mode to set the target graph when restoring the source graph to the target graph, legal values include [RESTORING, MERGING]
+ - --graph-mode or -m, the mode to set the target graph when restoring the source graph to the target graph, legal values include [RESTORING, MERGING], the default is RESTORING. The target graph is switched to this mode during the migration and switched back to its original mode afterwards
- --keep-local-data, whether to keep the backup of the source map generated in the process of migrating the map, the default is false, that is, the backup of the source map is not kept after the default migration map ends
- schedule-backup, periodically back up the graph and keep a certain number of the latest backups (currently only supports local file systems)
- --directory or -d, required, specifies the directory of the backup data
- --backup-num, optional, specifies the number of latest backups to save, defaults to 3
- - --interval, an optional item, specifies the backup cycle, the format is the same as the Linux crontab format
+ - --interval, an optional item, specifies the backup cycle, the format is the same as the Linux crontab format, the default is "0 0 * * *" (every day at 00:00)
+ > schedule-backup adds a crontab entry that runs `backup -t all` into `{directory}/{graph}/hugegraph-backup-{yyMMddHHmm}/` and keeps only the latest --backup-num backups. A relative --directory is resolved against the hugegraph-tools home directory, and `{directory}/{graph}` must not exist yet
- dump, export all vertices and edges in the graph, using the `vertex vertex-edge1 vertex-edge2...` JSON format by default.
To customize the format, implement a `Formatter` subclass such as `CustomFormatter` under `hugegraph-tools/src/main/java/org/apache/hugegraph/formatter`, then select it when running the command:
`bin/hugegraph dump -f CustomFormatter`
- --formatter or -f, specify the formatter to use, the default is JsonFormatter
- - --directory or -d, the directory where schema or data is stored, the default is the current directory
- - --log or -l, specify the log directory, the default is the current directory
+ - --directory or -d, the directory where schema or data is stored, the default is './{graphName}' for local directory, and '{fs.default.name}/{graphName}' for HDFS
+ - --log or -l, specify the log directory, the default is ./logs
- --retry, specify the number of failed retries, the default is 3
- - --split-size or -s, specifies the size of splitting vertices or edges when backing up, the default is 1048576
+ - --thread-num or -T, the number of threads to use, default is Math.min(10, Math.max(4, CPUs / 2))
+ - --split-size or -s, specifies the size of splitting vertices or edges when backing up, the default is 1048576, and it must be at least 1048576 (1M)
- -D, use the mode of -Dkey=value to specify dynamic parameters, and specify HDFS configuration items when backing up data to HDFS, for example: -Dfs.default.name=hdfs://localhost:9000
##### 3.7 Authentication data backup/restore type
- auth-backup, backup authentication data to a specified directory
- - --types or -t, types of authentication data to back up, separated by commas, optional value is 'all' or a combination of one or more [user, group, target, belong, access], 'all' represents all 5 types
- - --directory or -d, directory to store backup data, defaults to current directory
- - --log or -l, specify the log directory, the default is the current directory
+ - --types or -t, types of authentication data to back up, separated by commas, optional value is 'all' or a combination of one or more [user, group, target, belong, access], 'all' represents all 5 types; 'belong' requires 'user' and 'group' to be included, 'access' requires 'group' and 'target' to be included
+ - --directory, directory to store backup data, the default is './auth-backup-restore' for local directory, and '{fs.default.name}/auth-backup-restore' for HDFS (this option has no -d short form)
- --retry, specify the number of failed retries, the default is 3
- - --thread-num or -T, the number of threads to use, default is Math.min(10, Math.max(4, CPUs / 2))
- -D, use the mode of -Dkey=value to specify dynamic parameters, and specify HDFS configuration items when backing up data to HDFS, for example: -Dfs.default.name=hdfs://localhost:9000
- auth-restore, restore authentication data from a specified directory
- - --types or -t, types of authentication data to restore, separated by commas, optional value is 'all' or a combination of one or more [user, group, target, belong, access], 'all' represents all 5 types
- - --directory or -d, directory where backup data is stored, defaults to current directory
- - --log or -l, specify the log directory, the default is the current directory
+ - --types or -t, types of authentication data to restore, separated by commas, optional value is 'all' or a combination of one or more [user, group, target, belong, access], 'all' represents all 5 types; 'belong' requires 'user' and 'group' to be included, 'access' requires 'group' and 'target' to be included
+ - --directory, directory where backup data is stored, the default is './auth-backup-restore' for local directory, and '{fs.default.name}/auth-backup-restore' for HDFS (this option has no -d short form)
- --retry, specify the number of failed retries, the default is 3
- - --thread-num or -T, the number of threads to use, default is Math.min(10, Math.max(4, CPUs / 2))
- --strategy, conflict handling strategy, optional values are [stop, ignore], default is stop. stop means stop restoring when encountering conflicts, ignore means ignore conflicts and continue restoring
- - --init-password, initial password to set when restoring users, required when restoring user data
+ - --init-password, initial password to set when restoring users, required when --types includes user
- -D, use the mode of -Dkey=value to specify dynamic parameters, which are used to specify HDFS configuration items when restoring data from HDFS, for example: -Dfs.default.name=hdfs://localhost:9000
##### 3.8 Install the deployment type
- deploy, one-click download, install and start HugeGraph-Server and HugeGraph-Studio
- - -v, required, specifies the HugeGraph-Server and HugeGraph-Studio version to install
+ - -v, required, specifies the HugeGraph-Server and HugeGraph-Studio version to install, must be one of the versions listed in bin/version-map.yaml (0.6, 0.7, 0.8, 0.9, 0.10), which maps it to the matching server and studio release versions
- -p, required, specifies the installed HugeGraph-Server and HugeGraph-Studio directories
- -u, optional, specifies the link to download the HugeGraph-Server and HugeGraph-Studio compressed packages
-- clear, clean up HugeGraph-Server and HugeGraph-Studio directories and tarballs
+- clear, clean up HugeGraph-Server and HugeGraph-Studio directories and tarballs (refuses to run while a matching server or studio process is still alive, and prompts before each removal)
- -p, required, specifies the directory of HugeGraph-Server and HugeGraph-Studio to be cleaned
-- start-all, start HugeGraph-Server and HugeGraph-Studio with one click, and start monitoring, automatically pull up the service when the service dies
- - -v, required, specifies the installed HugeGraph-Server and HugeGraph-Studio version to start
+- start-all, start HugeGraph-Server and HugeGraph-Studio with one click
+ - -v, required, specifies the installed HugeGraph-Server and HugeGraph-Studio version to start, same values as deploy
- -p, required, specifies the directory where HugeGraph-Server and HugeGraph-Studio are installed
- stop-all, close HugeGraph-Server and HugeGraph-Studio with one click
-> There is an optional parameter -u in the deploy command. When provided, the specified download address will be used instead of the default download address to download the tar package, and the address will be written into the `~/hugegraph-download-url-prefix` file; if no address is specified later When -u and `~/hugegraph-download-url-prefix` are not specified, the tar package will be downloaded from the address specified by `~/hugegraph-download-url-prefix`; if there is neither -u nor `~/hugegraph-download-url-prefix`, it will be downloaded from the default download address
+> deploy, start-all, clear and stop-all are handed by `bin/hugegraph` straight to the shell scripts `bin/deploy.sh`, `bin/start-all.sh`, `bin/clear.sh` and `bin/stop-all.sh`, so the global options and environment variables in 3.2 do not apply to them.
+
+> There is an optional parameter -u in the deploy command. When provided, the specified download address will be used instead of the default download address to download the tar package, and the address will be written into the `~/hugegraph-download-url-prefix` file; if no address is specified later When -u and `~/hugegraph-download-url-prefix` are not specified, the tar package will be downloaded from the address specified by `~/hugegraph-download-url-prefix`; if there is neither -u nor `~/hugegraph-download-url-prefix`, it will be downloaded from the default download address `https://github.com/hugegraph`
Review Comment:
⚠️ Important: This newly documented default is not a usable release source for the versions accepted by `deploy`. `deploy.sh` combines it with `/hugegraph/releases/download/v${SERVER_VERSION}/...`; for `-v 0.8` that resolves to `https://github.com/hugegraph/hugegraph/releases/download/v0.8.0/hugegraph-0.8.0.tar.gz`, but that release is not published there. Please fix the script or document a verified download prefix/URL before advertising this default, and mirror the correction in the Chinese page.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] doc(toolchain): sync tools with master [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin merged PR #475:
URL: https://github.com/apache/hugegraph-doc/pull/475
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org