tahoe-lafs/trac-2024-07-25
2
0
Issues 1.1k Wiki Activity

Mention 'tahoe run' in running.html, and improve tahoe --help text #856

New issue
Closed
opened 2009-12-13 05:32:08 +00:00 by davidsarah · 15 comments
davidsarah commented 2009-12-13 05:32:08 +00:00
Owner
Copy link

From #355:

I guess you missed the existence of tahoe run because it isn't mentioned in source:docs/running.html. Perhaps we should change that document to describe tahoe run instead of tahoe start? (That document is intended for the beginner, who might prefer the simplicity of tahoe run.)

Something else that might help is if the output of tahoe --help separated node control (start, stop, restart, run, create-client, create-introducer) from filesystem usage (put, get, rm, etc.)

These seem like good doc improvements to me. They're independent of the other problems with tahoe run in #355.

From #355: > I guess you missed the existence of `tahoe run` because it isn't mentioned in source:docs/running.html. Perhaps we should change that document to describe `tahoe run` instead of `tahoe start`? (That document is intended for the beginner, who might prefer the simplicity of `tahoe run`.) > Something else that might help is if the output of `tahoe --help` separated node control (`start`, `stop`, `restart`, `run`, `create-client`, `create-introducer`) from filesystem usage (`put`, `get`, `rm`, etc.) These seem like good doc improvements to me. They're independent of the other problems with `tahoe run` in #355.
tahoe-lafs added the
code-frontend-cli
major
enhancement
1.5.0
 labels 2009-12-13 05:32:08 +00:00
tahoe-lafs added this to the 1.6.0 milestone 2009-12-13 05:32:08 +00:00
warner commented 2010-01-09 03:08:41 +00:00
Author
Owner
Copy link

FYI, I don't think there's a way to override the alphabetical sorting of subcommands in twisted.python.usage.Option's base-class code which generates the output that "bin/tahoe" (without a subcommand) provokes. But if you override the "getUsage" method on allmydata.scripts.runner.Options (using allmydata.scripts.cli.GetOptions.getUsage as a template), you can probably replace the command listing with different text. This might be a good place to emit something else, like:

Commands for node admin:
   create-client       Create a client node.
   create-introducer   ...
   create-key-generator
   create-stats-gatherer
   start
   stop
   restart
   run
Commands for filesystem manipulation:
   mkdir
   ls
   cp
   ...
FYI, I don't think there's a way to override the alphabetical sorting of subcommands in `twisted.python.usage.Option`'s base-class code which generates the output that "bin/tahoe" (without a subcommand) provokes. But if you override the "getUsage" method on `allmydata.scripts.runner.Options` (using `allmydata.scripts.cli.GetOptions.getUsage` as a template), you can probably replace the command listing with different text. This might be a good place to emit something else, like: ``` Commands for node admin: create-client Create a client node. create-introducer ... create-key-generator create-stats-gatherer start stop restart run Commands for filesystem manipulation: mkdir ls cp ... ```
warner commented 2010-01-09 03:29:12 +00:00
Author
Owner
Copy link

Oh, one correction, usage.Option doesn't just sort its subcommands alphabetically: it retains the order in which they were provided (notice that bin/tahoe's output puts all the create-node commands at the start, and all the start/stop commands at the end.. this matches the way that _general_commands and subCommands are built in src/allmydata/scripts/runner.py).

That probably doesn't help insert extra text into the usage output, though.. you'll probably still have to override getUsage. But consider upcalling and then inserting text into the result (instead of writing something entirely new), because doing it that way will be more robust against the addition of new subcommands in the future.

Oh, one correction, usage.Option doesn't just sort its subcommands alphabetically: it retains the order in which they were provided (notice that `bin/tahoe`'s output puts all the create-node commands at the start, and all the start/stop commands at the end.. this matches the way that `_general_commands` and `subCommands` are built in src/allmydata/scripts/runner.py). That probably doesn't help insert extra text into the usage output, though.. you'll probably still have to override getUsage. But consider upcalling and then inserting text into the result (instead of writing something entirely new), because doing it that way will be more robust against the addition of new subcommands in the future.
davidsarah commented 2010-01-09 23:50:48 +00:00
Author
Owner
Copy link

Attachment running.html_diff.txt (2280 bytes) added

Diff for source:docs/running.html to describe tahoe run

**Attachment** running.html_diff.txt (2280 bytes) added Diff for source:docs/running.html to describe tahoe run
running.html_diff.txt
2.2 KiB
davidsarah commented 2010-01-10 02:10:38 +00:00
Author
Owner
Copy link

New help text:

$ tahoe
Usage:  tahoe <command> [command options]
Options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers and exit.
      --version-and-path  Display version numbers and paths to their locations
                          and exit.
      --help              Display this help and exit.
Commands:

Node adminstration
    create-client              Create a client node.
    create-introducer          Create a introducer node.
    create-key-generator       Create a key generator service.
    create-stats-gatherer      Create a stats-gatherer service.

Using the filesystem
    mkdir                      Create a new directory
    add-alias                  Add a new alias cap
    create-alias               Create a new alias cap
    list-aliases               List all alias caps
    ls                         List a directory
    get                        Retrieve a file from the virtual drive.
    put                        Upload a file into the virtual drive.
    cp                         Copy one or more files.
    rm                         Unlink a file or directory in the virtual drive.
    mv                         Move a file within the virtual drive.
    ln                         Make an additional link to an existing file.
    backup                     Make target dir look like local dir.
    webopen                    Open a webbrowser to the root_dir
    manifest                   List all files/dirs in a subtree
    stats                      Print statistics about all files/dirs in a
                               subtree
    check                      Check a single file or directory
    deep-check                 Check all files/directories reachable from a
                               starting point

Debugging
    debug                      debug subcommands: use 'tahoe debug' for a list

Controlling a node
    start                      Start a node (of any type).
    stop                       Stop a node.
    restart                    Restart a node.
    run                        Run a node synchronously.

c:\Python26\Scripts\tahoe-script.py:  must specify a command
New help text: ``` $ tahoe Usage: tahoe <command> [command options] Options: -q, --quiet Operate silently. -V, --version Display version numbers and exit. --version-and-path Display version numbers and paths to their locations and exit. --help Display this help and exit. Commands: Node adminstration create-client Create a client node. create-introducer Create a introducer node. create-key-generator Create a key generator service. create-stats-gatherer Create a stats-gatherer service. Using the filesystem mkdir Create a new directory add-alias Add a new alias cap create-alias Create a new alias cap list-aliases List all alias caps ls List a directory get Retrieve a file from the virtual drive. put Upload a file into the virtual drive. cp Copy one or more files. rm Unlink a file or directory in the virtual drive. mv Move a file within the virtual drive. ln Make an additional link to an existing file. backup Make target dir look like local dir. webopen Open a webbrowser to the root_dir manifest List all files/dirs in a subtree stats Print statistics about all files/dirs in a subtree check Check a single file or directory deep-check Check all files/directories reachable from a starting point Debugging debug debug subcommands: use 'tahoe debug' for a list Controlling a node start Start a node (of any type). stop Stop a node. restart Restart a node. run Run a node synchronously. c:\Python26\Scripts\tahoe-script.py: must specify a command ```
davidsarah commented 2010-01-10 03:03:45 +00:00
Author
Owner
Copy link

Rearranging the command groups and adding some text about tahoe <command> --help at the bottom:

$ tahoe --help
Usage:  tahoe <command> [command options]
Options:
  -q, --quiet             Operate silently.
  -V, --version           Display version numbers and exit.
      --version-and-path  Display version numbers and paths to their locations
                          and exit.
      --help              Display this help and exit.
Commands:

Administration
    create-client              Create a client node.
    create-introducer          Create a introducer node.
    create-key-generator       Create a key generator service.
    create-stats-gatherer      Create a stats-gatherer service.

Controlling a node
    start                      Start a node (of any type).
    stop                       Stop a node.
    restart                    Restart a node.
    run                        Run a node synchronously.

Debugging
    debug                      debug subcommands: use 'tahoe debug' for a list

Using the filesystem
    mkdir                      Create a new directory
    add-alias                  Add a new alias cap
    create-alias               Create a new alias cap
    list-aliases               List all alias caps
    ls                         List a directory
    get                        Retrieve a file from the virtual drive.
    put                        Upload a file into the virtual drive.
    cp                         Copy one or more files.
    rm                         Unlink a file or directory in the virtual drive.
    mv                         Move a file within the virtual drive.
    ln                         Make an additional link to an existing file.
    backup                     Make target dir look like local dir.
    webopen                    Open a webbrowser to the root_dir
    manifest                   List all files/dirs in a subtree
    stats                      Print statistics about all files/dirs in a
                               subtree
    check                      Check a single file or directory
    deep-check                 Check all files/directories reachable from a
                               starting point

Please run 'tahoe <command> --help' for more details on each command.
Rearranging the command groups and adding some text about `tahoe <command> --help` at the bottom: ``` $ tahoe --help Usage: tahoe <command> [command options] Options: -q, --quiet Operate silently. -V, --version Display version numbers and exit. --version-and-path Display version numbers and paths to their locations and exit. --help Display this help and exit. Commands: Administration create-client Create a client node. create-introducer Create a introducer node. create-key-generator Create a key generator service. create-stats-gatherer Create a stats-gatherer service. Controlling a node start Start a node (of any type). stop Stop a node. restart Restart a node. run Run a node synchronously. Debugging debug debug subcommands: use 'tahoe debug' for a list Using the filesystem mkdir Create a new directory add-alias Add a new alias cap create-alias Create a new alias cap list-aliases List all alias caps ls List a directory get Retrieve a file from the virtual drive. put Upload a file into the virtual drive. cp Copy one or more files. rm Unlink a file or directory in the virtual drive. mv Move a file within the virtual drive. ln Make an additional link to an existing file. backup Make target dir look like local dir. webopen Open a webbrowser to the root_dir manifest List all files/dirs in a subtree stats Print statistics about all files/dirs in a subtree check Check a single file or directory deep-check Check all files/directories reachable from a starting point Please run 'tahoe <command> --help' for more details on each command. ```
warner commented 2010-01-10 08:41:05 +00:00
Author
Owner
Copy link

wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that self.subCommands gets set back to its original value even if an exception is raised in the middle, but that code is only going to get invoked after subCommands is used and just before the whole process exits, so it probably isn't too important.

Please double-check that the trick you're using will work against our oldest supported version of Twisted (which is.. aagh! zooko! well, it used to be in README, and then in INSTALL, and now I can't find it in the docs/ directory. So first harass Zooko to ressurect our human-readable dependency list, then check it for the oldest version of Twisted that we claim compatibility with, and then check that version of Twisted :). I believe usage.Options has remained unchanged for years, so I expect your trick to work everywhere, but it'd be good to make sure.

wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that `self.subCommands` gets set back to its original value even if an exception is raised in the middle, but that code is only going to get invoked after subCommands is used and just before the whole process exits, so it probably isn't too important. Please double-check that the trick you're using will work against our oldest supported version of Twisted (which is.. aagh! zooko! well, it used to be in README, and then in INSTALL, and now I can't find it in the docs/ directory. So first harass Zooko to ressurect our human-readable dependency list, then check it for the oldest version of Twisted that we claim compatibility with, and then check that version of Twisted :). I believe usage.Options has remained unchanged for years, so I expect your trick to work everywhere, but it'd be good to make sure.
zooko commented 2010-01-10 18:30:31 +00:00
Author
Owner
Copy link

Our "human-readable" dependency list is in source:_auto_deps.py, and it says "Twisted >= 2.4.0". If David-Sarah's hack doesn't work with Twisted 2.4.0 we should consider raising the minimum version requirement. Currently on our Supported builders the oldest version of Twisted in use is Twisted 8.1.0 (in Debian 5.0 Lenny and in NetBSD 4). If David-Sarah's hack works for all versions of Twisted > X for some X <= 8.1.0 then I would support it.

Our "human-readable" dependency list is in source:_auto_deps.py, and it says `"Twisted >= 2.4.0"`. If David-Sarah's hack doesn't work with Twisted 2.4.0 we should consider raising the minimum version requirement. Currently on our Supported builders the oldest version of Twisted in use is Twisted 8.1.0 (in Debian 5.0 Lenny and in NetBSD 4). If David-Sarah's hack works for all versions of Twisted > X for some X <= 8.1.0 then I would support it.
warner commented 2010-01-10 20:57:26 +00:00
Author
Owner
Copy link

ok, I think we need a pointer to it from some other human-readable document, like the way that most projects have a README or an INSTALL which tells you what the dependencies are (grep auto_deps README docs/* shows nothing). I know that you've tried hard to not frighten people with such details, but I think they need to be findable by the people who want them.

But anyways, I don't see any changes to twisted.python.usage between 2.4.0 and current trunk (which is 9.0.0+), so I think David-Sarah's hack should work equally well across that range.

ok, I think we need a pointer to it from some other human-readable document, like the way that most projects have a README or an INSTALL which tells you what the dependencies are (`grep auto_deps README docs/*` shows nothing). I know that you've tried hard to not frighten people with such details, but I think they need to be findable by the people who want them. But anyways, I don't see any changes to twisted.python.usage between 2.4.0 and current trunk (which is 9.0.0+), so I think David-Sarah's hack should work equally well across that range.
davidsarah commented 2010-01-10 21:04:06 +00:00
Author
Owner
Copy link

Looking at the source for Twisted's usage.py, this hack should work going back to revision 7653 in July 2003, which introduced the getUsage method. We depend on getUsage elsewhere, e.g. in cli.py. That would have been way before Twisted 2.4.0, which was released in 2006.

I agree about the try: finally:.

Looking at the source for Twisted's `usage.py`, this hack *should* work going back to [revision 7653](http://twistedmatrix.com/trac/browser/trunk/twisted/python/usage.py?rev=7653) in July 2003, which introduced the `getUsage` method. We depend on `getUsage` elsewhere, e.g. in `cli.py`. That would have been way before Twisted 2.4.0, which was released in 2006. I agree about the `try: finally:`.
davidsarah commented 2010-01-11 05:23:20 +00:00
Author
Owner
Copy link

Attachment runner.py_diff.txt (2010 bytes) added

Diff for source:src/allmydata/scripts/runner.py to split usage into groups (better approach)

**Attachment** runner.py_diff.txt (2010 bytes) added Diff for source:src/allmydata/scripts/runner.py to split usage into groups (better approach)
runner.py_diff.txt
2 KiB
davidsarah commented 2010-01-12 04:38:04 +00:00
Author
Owner
Copy link

Replying to warner:

wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that self.subCommands gets set back to its original value even if an exception is raised in the middle, [...]

I changed it to use another class so that self.subCommands doesn't need to be modified in the Options instance.

Replying to [warner](/tahoe-lafs/trac-2024-07-25/issues/856#issuecomment-115618): > wow, that's awesome, in a kinda scary way :). I'd sort of suggest using a try:finally: clause to make sure that `self.subCommands` gets set back to its original value even if an exception is raised in the middle, [...] I changed it to use another class so that `self.subCommands` doesn't need to be modified in the `Options` instance.
davidsarah commented 2010-01-12 04:46:53 +00:00
Author
Owner
Copy link

Attachment tahoe-help-group-commands.darcspatch.txt (36634 bytes) added

Split tahoe --help options into groups

**Attachment** tahoe-help-group-commands.darcspatch.txt (36634 bytes) added Split tahoe --help options into groups
tahoe-help-group-commands.darcspatch.txt
36 KiB
davidsarah commented 2010-01-12 04:50:55 +00:00
Author
Owner
Copy link

Attachment change-running-html-to-describe-tahoe-run.darcspatch.txt (36458 bytes) added

Change running.html to describe 'tahoe run'

**Attachment** change-running-html-to-describe-tahoe-run.darcspatch.txt (36458 bytes) added Change running.html to describe 'tahoe run'
change-running-html-to-describe-tahoe-run.darcspatch.txt
36 KiB
davidsarah commented 2010-01-24 21:55:07 +00:00
Author
Owner
Copy link

The command grouping is a very simple patch, and I think it does help make the tahoe --help text more readable. Anyone want to review it for 1.6?

The command grouping is a very simple patch, and I think it does help make the `tahoe --help text` more readable. Anyone want to review it for 1.6?
zooko commented 2010-01-26 04:56:29 +00:00
Author
Owner
Copy link

Thank you! I really like the command grouping! Applied as changeset:b94b9af1896ec527, changeset:b079f32da2aa0746, changeset:a1444d9367554df7, and changeset:5c04fd689ab4b3bf.

Thank you! I really like the command grouping! Applied as changeset:b94b9af1896ec527, changeset:b079f32da2aa0746, changeset:a1444d9367554df7, and changeset:5c04fd689ab4b3bf.
tahoe-lafs added the
fixed
 label 2010-01-26 04:56:29 +00:00
zooko closed this issue 2010-01-26 04:56:29 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
No results found.
No results found.
Labels
Clear labels   
0.2.0

   
0.3.0

   
0.4.0

   
0.5.0

   
0.5.1

   
0.6.0

   
0.6.1

   
0.7.0

   
0.8.0

   
0.9.0

   
1.0.0

   
1.1.0

   
1.10.0

   
1.10.1

   
1.10.2

   
1.10a2

   
1.11.0

   
1.12.0

   
1.12.1

   
1.13.0

   
1.14.0

   
1.15.0

   
1.15.1

   
1.2.0

   
1.3.0

   
1.4.1

   
1.5.0

   
1.6.0

   
1.6.1

   
1.7.0

   
1.7.1

   
1.7β

   
1.8.0

   
1.8.1

   
1.8.2

   
1.8.3

   
1.8β

   
1.9.0

   
1.9.0-s3branch

   
1.9.0a1

   
1.9.0a2

   
1.9.0b1

   
1.9.1

   
1.9.2

   
1.9.2a1

   
LeastAuthority.com automation

   
blocker

   
cannot reproduce

   
cloud-branch

   
code

catch-all for anything that can be fixed by writing code but isn't classified better

  
code-dirnodes

anything involving tahoe directories

  
code-encoding

immutable-file encoding format/layout, cap format, encoding/decoding algorithms

  
code-frontend

general frontend things: new user-facing interfaces, FTP/SFTP servers, FUSE-like interfaces

  
code-frontend-cli

CLI tools

  
code-frontend-ftp-sftp

   
code-frontend-magic-folder

   
code-frontend-web

webapi interfaces, user-facing "WUI" interfaces

  
code-mutable

anything involving mutable files: encoding/decoding, share format

  
code-network

Introducer, locating storage servers, establishing/maintaining connections to them

  
code-nodeadmin

node startup/shutdown, tools to create nodes, logging tools, management/monitoring tools, manhole, disk-space-limiting tools

  
code-peerselection

server selection/sorting algorithm, rebalancing code, allocation policy, swarming-download

  
code-storage

storage-server implementation, share-storage directory layout, client-to-server share transfer protocol

  
contrib

problems with non-core things that live in the source:contrib/ directory

  
critical

   
defect

   
dev-infrastructure

things that help us build Tahoe: buildbot, automated speed/memory/code-coverage tests and results-displayers, IRC channels, mailing lists, this Trac instance

  
documentation

docs items. Also use 'docs' keyword on tickets in more specific components.

  
duplicate

   
enhancement

   
fixed

   
invalid

   
major

   
minor

   
n/a

   
normal

   
operational

things involved in running a tahoe grid, external tools to monitor/maintain a grid (like "nodeadmin" but larger-scale). Was also used for issues with the allmydata.com grid.

  
packaging

setup.py script, library dependencies, binary packages, licensing, installation instructions

  
somebody else's problem

   
supercritical

   
task

   
trivial

   
unknown

Uncategorized. All tickets default to this component until someone updates it.

  
was already fixed

   
website

things about the tahoe-lafs.org website (and sometimes this Trac instance, shared with 'dev-infrastructure')

  
wontfix

   
worksforme
No labels
0.2.0
0.3.0
0.4.0
0.5.0
0.5.1
0.6.0
0.6.1
0.7.0
0.8.0
0.9.0
1.0.0
1.1.0
1.10.0
1.10.1
1.10.2
1.10a2
1.11.0
1.12.0
1.12.1
1.13.0
1.14.0
1.15.0
1.15.1
1.2.0
1.3.0
1.4.1
1.5.0
1.6.0
1.6.1
1.7.0
1.7.1
1.7β
1.8.0
1.8.1
1.8.2
1.8.3
1.8β
1.9.0
1.9.0-s3branch
1.9.0a1
1.9.0a2
1.9.0b1
1.9.1
1.9.2
1.9.2a1
LeastAuthority.com automation
blocker
cannot reproduce
cloud-branch
code
code-dirnodes
code-encoding
code-frontend
code-frontend-cli
code-frontend-ftp-sftp
code-frontend-magic-folder
code-frontend-web
code-mutable
code-network
code-nodeadmin
code-peerselection
code-storage
contrib
critical
defect
dev-infrastructure
documentation
duplicate
enhancement
fixed
invalid
major
minor
n/a
normal
operational
packaging
somebody else's problem
supercritical
task
trivial
unknown
was already fixed
website
wontfix
worksforme
Milestone
Clear milestone
No items
No milestone
1.6.0
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: tahoe-lafs/trac-2024-07-25#856
No description provided.
Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?