From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp2.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms13.migadu.com with LMTPS id gNImO/9UM2ebFQEAe85BDQ:P1 (envelope-from ) for ; Tue, 12 Nov 2024 13:15:44 +0000 Received: from aspmx1.migadu.com ([2001:41d0:403:4876::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp2.migadu.com with LMTPS id gNImO/9UM2ebFQEAe85BDQ (envelope-from ) for ; Tue, 12 Nov 2024 14:15:44 +0100 X-Envelope-To: larch@yhetil.org Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=elephly.net header.s=zoho header.b=Hxd4iyuS; dmarc=none; arc=pass ("zohomail.com:s=zohoarc:i=1"); spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" ARC-Seal: i=2; s=key1; d=yhetil.org; t=1731417343; a=rsa-sha256; cv=pass; b=NXkwz8e8JLLPRxD6yw9BHpE3+Y4dJg5Ih0ukZlXkggkMRAUInz+cC1WzjEDUK8nfT7jtgM TJwHPZAgpss+TtEbVoYSvhZonDKwQl1X45u8YzPBA1qEBNWoOtUA1TZd/PEcL9bFatAi++ IJYGmYpXP54Hw0eMdEt1YX0+dIKU56ok6ri5mODohHluBhS4Kfk9UqMZ+PKSh+IrERBaOy GnHdHGbzc+frOKaEWApsMzK6cVcoSoKUO15HyhPVdKOnRu7l/lXZ1EfADqWw0ZkaAAp0QN rwDaRfkbmDntXLDUaWII/oXMerUXGBQsqOFdG2tJeXipqRVjS/WOT9H9wUUeEA== ARC-Authentication-Results: i=2; aspmx1.migadu.com; dkim=pass header.d=elephly.net header.s=zoho header.b=Hxd4iyuS; dmarc=none; arc=pass ("zohomail.com:s=zohoarc:i=1"); spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org" ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1731417343; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=TRi51YtiuuHTg4Ypvpmyj11oaMhgKaNvxbcNUGGwAwY=; b=Sp2w6RbjKRYnGbCnxgmZARIa6lbYdNndrf/C1QyQ2eq0jJzeyY4ovJ8a7LcfaLh9nQHLsJ dc9jxWywNcz4vp8Js+LQn+ezPsW+u5m+f8Sf9slCJNlcU7wJCmMGSd2x8jZpy+aug+Iczh 0DX4wetSf7jWktDDmYQXbKW6rULi6J/KhH0aoOWgvTDk6Kh2Zgej/TTm5LOsMHov+UxQ/t 533KwA/WHFob93z33gk4SJtWtVP9vNZYZKA2quO6ZiL1iRqEdjDlI5ey2+Dhrxb3QsV8XU LSOXuvXU/v95Q3AKZHw1HUWuNuXI92aaQiZWrMb7UnOUpBngCMt4gBpRbbduCw== Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 0557377151 for ; Tue, 12 Nov 2024 14:15:42 +0100 (CET) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tAqjX-0002zp-BK; Tue, 12 Nov 2024 08:15:03 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tAqjT-0002yc-F8 for guix-devel@gnu.org; Tue, 12 Nov 2024 08:14:59 -0500 Received: from sender4-of-o51.zoho.com ([136.143.188.51]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tAqjQ-0006Cg-Af for guix-devel@gnu.org; Tue, 12 Nov 2024 08:14:58 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1731417290; cv=none; d=zohomail.com; s=zohoarc; b=Nhzp6XdymPqX3P4b01i+nj+e4xXmL5NaqhTmBWhsAHyZjxThO/TyS62SNaVX9HL/b7cT9oziXGAByj4+z2nSFL7gW0qdh/oTro/hb22+fqh/2MCnPkZHnJ1VQQokM9ywNELgJHoSEKfHVyCAi6lySRSkG+PFW9WW1tEoSl4tkiI= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1731417290; h=Content-Type:Date:Date:From:From:MIME-Version:Message-ID:Subject:Subject:To:To:Message-Id:Reply-To:Cc; bh=TRi51YtiuuHTg4Ypvpmyj11oaMhgKaNvxbcNUGGwAwY=; b=IY3A/zwH7w4U6RhGjbIVnSZL3YhUVYY2QJqau0hyqk87GE1SxsV5rGKbIo+Cq94H3SBBbs+9pduzMf/OmLO6c5m/Cd9FfZfqygNzCN3sqOv6H3xbzWEtOu31oxeRcxn7zkMHl0Zfpc3Bu5Vfy1Lrrd12dXRBG+hDAWluh1cfZ0c= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=elephly.net; spf=pass smtp.mailfrom=rekado@elephly.net; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1731417290; s=zoho; d=elephly.net; i=rekado@elephly.net; h=From:From:To:To:Subject:Subject:Date:Date:Message-ID:MIME-Version:Content-Type:Message-Id:Reply-To:Cc; bh=TRi51YtiuuHTg4Ypvpmyj11oaMhgKaNvxbcNUGGwAwY=; b=Hxd4iyuSyc3NRg4waLxUeCdZgzFGh3om7btC/YYxnFXGhpdvWB5h/cIWnbPxmOa4 HoBIzY9iHa/oX9SaEBzB+pH1VHa+CljKbyn2+kGpTD7I0EEZddo3Wbv6MFwxr8NpDL1 PNRIsxuOB2T31DOq8s9CSMGpsVQuNX5SwDce4EDs= Received: by mx.zohomail.com with SMTPS id 173141728866521.216373090103843; Tue, 12 Nov 2024 05:14:48 -0800 (PST) From: Ricardo Wurmus To: guix-devel@gnu.org Subject: Unhelpful "--help" output Date: Tue, 12 Nov 2024 14:14:45 +0100 Message-ID: <877c98egqi.fsf@elephly.net> MIME-Version: 1.0 Content-Type: text/plain X-ZohoMailClient: External Received-SPF: pass client-ip=136.143.188.51; envelope-from=rekado@elephly.net; helo=sender4-of-o51.zoho.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: guix-devel-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Spam-Score: -5.29 X-Spam-Score: -5.29 X-Migadu-Queue-Id: 0557377151 X-Migadu-Scanner: mx10.migadu.com X-TUID: OtqVEcqg9TVO Hi Guix, I found the help output not to be very helpful whenever there are sub-commands. The output contains options that are not relevant to the sub-command. The options also don't appear to be ordered. Here is an example. I want to know more about "guix system docker-image", so I run "guix system docker-image --help". This is the output I get: --8<---------------cut here---------------start------------->8--- Usage: guix system [OPTION ...] ACTION [ARG ...] [FILE] Build the operating system declared in FILE according to ACTION. Some ACTIONS support additional ARGS. The valid values for ACTION are: search search for existing service types edit edit the definition of an existing service type reconfigure switch to a new operating system configuration roll-back switch to the previous operating system configuration describe describe the current system list-generations list the system generations switch-generation switch to an existing operating system configuration delete-generations delete old system generations build build the operating system without installing anything container build a container that shares the host's store vm build a virtual machine image that shares the host's store image build a Guix System image docker-image build a Docker image init initialize a root file system to run GNU extension-graph emit the service extension graph in Dot format shepherd-graph emit the graph of shepherd services in Dot format -L, --load-path=DIR prepend DIR to the package module search path -K, --keep-failed keep build tree of failed builds -k, --keep-going keep going when some of the derivations fail -n, --dry-run do not build the derivations --fallback fall back to building when the substituter fails --no-substitutes build instead of resorting to pre-built substitutes --substitute-urls=URLS fetch substitute from URLS if they are authorized --no-grafts do not graft packages --no-offload do not attempt to offload builds --max-silent-time=SECONDS mark the build as failed after SECONDS of silence --timeout=SECONDS mark the build as failed after SECONDS of activity --rounds=N build N times in a row to detect non-determinism -c, --cores=N allow the use of up to N CPU cores for the build -M, --max-jobs=N allow at most N build jobs --debug=LEVEL produce debugging output at LEVEL -d, --derivation return the derivation of the given system -e, --expression=EXPR consider the operating-system EXPR evaluates to instead of reading FILE, when applicable --allow-downgrades for 'reconfigure', allow downgrades to earlier channel revisions --on-error=STRATEGY apply STRATEGY (one of nothing-special, backtrace, or debug) when an error occurs while reading FILE --list-image-types list available image types -t, --image-type=TYPE for 'image', produce an image of TYPE --image-size=SIZE for 'image', produce an image of SIZE --no-bootloader for 'init', do not install a bootloader --volatile for 'image', make the root file system volatile --persistent for 'vm', make the root file system persistent --label=LABEL for 'image', label disk image with LABEL --save-provenance save provenance information --share=SPEC for 'vm' and 'container', share host file system with read/write access according to SPEC --expose=SPEC for 'vm' and 'container', expose host file system directory as read-only according to SPEC -N, --network for 'container', allow containers to access the network -r, --root=FILE for 'vm', 'image', 'container' and 'build', make FILE a symlink to the result, and register it as a garbage collector root --full-boot for 'vm', make a full boot sequence --no-graphic for 'vm', use the tty that we are started in for IO --skip-checks skip file system and initrd module safety checks -v, --verbosity=LEVEL use the given verbosity LEVEL --graph-backend=BACKEND use BACKEND for 'extension-graph' and 'shepherd-graph' -I, --list-installed[=REGEXP] for 'describe' and 'list-generations', list installed packages matching REGEXP --list-targets list available targets --target=TRIPLET cross-build for TRIPLET--e.g., "aarch64-linux-gnu" --list-systems list available systems -s, --system=SYSTEM attempt to build for SYSTEM--e.g., "i686-linux" --help-docker-format list options specific to the docker image type. -h, --help display this help and exit -V, --version display version information and exit Report bugs to: bug-guix@gnu.org. GNU Guix home page: General help using Guix and GNU software: --8<---------------cut here---------------end--------------->8--- Note that this is the same output as for "guix system --help". I don't think it's great to see all these "for 'vm'" qualifiers on the right-hand side. Here is what I propose: - In the case of commands that offer sub-commands, remove *all* the options from the help output of the main command (e.g. "guix system --help"), and only showing the list of available sub-commands. - For "guix [command] [sub-command] --help" show only options to this sub-command. - optionally, group all generic options (e.g. --system, --help, --version, etc) under a single heading. What do you think? -- Ricardo