Update shell completion and manpage (flameshot-org#4140)

mmahmoudian · web-flow · commit 9891ab07ccb5 · 2025-08-09T19:35:14.000-05:00
* update the shell completions to include everything in --help of each subcommand

* re-arrange and update the manpage
diff --git a/data/man/man1/flameshot.1 b/data/man/man1/flameshot.1
@@ -83,6 +83,14 @@ If no argument is provided, it will open the config window, otherwise it can cha
 Here we list all the arguments available for all subcommands. The subcommands that accept each argument are listed after each argument. Alternatively, you can use the \fBflameshot [subcommand] --help\fR to know the list of available arguments for each subcommand.
 .
 .PP
+\-s, \-\-accept-on-select
+.RS 4
+Accept capture as soon as a selection is made
+.br
+Valid for subcommands: gui
+.RE
+.
+.PP
 \-a, \-\-autostart <bool>
 .RS 4
 Enable or disable run at startup
@@ -107,6 +115,14 @@ Valid for subcommands: full, gui, screen
 .RE
 .
 .PP
+\-k, \-\-contrastcolor <color-code>
+.RS 4
+Define the contrast UI color
+.br
+Valid for subcommands: config
+.RE
+.
+.PP
 \-d, \-\-delay <milliseconds>
 .RS 4
 How many milliseconds should Flameshot wait before taking the screenshot
@@ -123,14 +139,6 @@ Valid for subcommands: config
 .RE
 .
 .PP
-\-g, \-\-print-geometry
-.RS 4
-Print geometry of the selection in the format WxH+X+Y. Does nothing if raw is specified
-.br
-Valid for subcommands: gui
-.RE
-.
-.PP
 \-h, \-\-help
 .RS 4
 Show a brief help message and list the arguments the valid arguments for that subcommand
@@ -139,25 +147,25 @@ Valid for subcommands: config, full, gui, launcher, screen
 .RE
 .
 .PP
-\-k, \-\-contrastcolor <color-code>
+\-\-last-region
 .RS 4
-Define the contrast UI color
+Repeat screenshot with previously selected region
 .br
-Valid for subcommands: config
+Valid for subcommands: gui
 .RE
 .
 .PP
-\-\-last-region
+\-m, \-\-maincolor <color-code>
 .RS 4
-Repeat screenshot with previously selected region
+Define the main UI color
 .br
-Valid for subcommands: full, gui, screen
+Valid for subcommands: config
 .RE
 .
 .PP
-\-m, \-\-maincolor <color-code>
+\-n, \-\-notifications
 .RS 4
-Define the main UI color
+Enable or disable the notifications
 .br
 Valid for subcommands: config
 .RE
@@ -187,27 +195,27 @@ Valid for subcommands: gui, screen
 .RE
 .
 .PP
-\-r, \-\-raw
+\-g, \-\-print-geometry
 .RS 4
-Send raw PNG to stdout
+Print geometry of the selection in the format WxH+X+Y. Does nothing if raw is specified
 .br
-Valid for subcommands: full, gui, screen
+Valid for subcommands: gui
 .RE
 .
 .PP
-\-\-region <WxH+X+Y or string>  
+\-r, \-\-raw
 .RS 4
-Screenshot region to select
+Send raw PNG to stdout
 .br
 Valid for subcommands: full, gui, screen
 .RE
 .
 .PP
-\-s, \-\-accept-on-select
+\-\-region <WxH+X+Y or string>  
 .RS 4
-Accept capture as soon as a selection is made
+Screenshot region to select
 .br
-Valid for subcommands: gui
+Valid for subcommands: full, gui, screen
 .RE
 .
 .PP
diff --git a/data/shell-completion/flameshot.bash b/data/shell-completion/flameshot.bash
@@ -4,17 +4,18 @@
 # To be installed in "/usr/share/bash-completion/completions/flameshot"
 # and "/usr/share/zsh/site-functions/"
 
+
 _flameshot() {
 	local prev cur cmd gui_opts full_opts config_opts
 	COMPREPLY=()
 
 	prev="${COMP_WORDS[COMP_CWORD-1]}"
 	cur="${COMP_WORDS[COMP_CWORD]}"
 	cmd="gui full config launcher screen"
-	screen_opts="--number --path --delay --raw --last-region -p -d -r -n"
-	gui_opts="--path --delay --raw --last-region -p -d -r"
-	full_opts="--path --delay --clipboard --raw --last-region -p -d -c -r"
-	config_opts="--contrastcolor --filename --maincolor --showhelp --trayicon --autostart -k -f -m -s -t -a"
+	screen_opts="--number -n --path -p --clipboard -c --delay -d --region --raw -r --upload -u --pin --help"
+	gui_opts="--path -p --clipboard -c --delay -d --region --last-region --raw -r --print-geometry -g --upload -u --pin --accept-on-select -s --help"
+	full_opts="--path -p --clipboard -c --delay -d --region --raw -r --upload -u --help"
+	config_opts="--autostart -a --filename -f --notifications -n --trayicon -t --showhelp -s --maincolor -m --contrastcolor -k --check"
 
 	case "${prev}" in
 		launcher)
@@ -40,7 +41,8 @@ _flameshot() {
 			_filedir -d
 			return 0
 			;;
-		-s|--showhelp|-t|--trayicon)
+        # TODO: We should see how we can add the -n (for `config --notifications`) here that does not conflict with -n (for `screen --number`)
+		-a|--autostart|-s|--showhelp|-t|--trayicon|--notifications)
 			COMPREPLY=( $(compgen -W "true false" -- "${cur}") )
 			return 0
 			;;
diff --git a/data/shell-completion/flameshot.fish b/data/shell-completion/flameshot.fish
@@ -1,4 +1,3 @@
-set -l SUBCOMMANDS gui screen full launcher config
 
 ####################
 # HELPER FUNCTIONS #
@@ -67,48 +66,61 @@ end
 # COMPLETIONS #
 ###############
 
+# define the subcommands
+set -l SUBCOMMANDS gui screen full launcher config
+
 # No subcommand
-complete -c flameshot -n __flameshot_no_positional_args -f -a "$SUBCOMMANDS"
-complete -c flameshot -l "help"                 -s "h"  -f   -d "Display help message"
-complete -c flameshot -l "version"              -s "v"  -f   -d "Display version information" -n __flameshot_no_positional_args
+complete -c flameshot                                                                                        --no-files --arguments "$SUBCOMMANDS" --condition __flameshot_no_positional_args 
+complete -c flameshot --long-option "help"    --short-option "h" --description "Display help message"        --no-files
+complete -c flameshot --long-option "version" --short-option "v" --description "Display version information" --no-files                            --condition __flameshot_no_positional_args
 
 # GUI subcommand
-__flameshot_complete gui                                -f
-__flameshot_complete gui -l "path"              -s "p"  -rk  -d "Output file or directory"
-__flameshot_complete gui -l "clipboard"         -s "c"  -f   -d "Copy screenshot to the clipboard"
-__flameshot_complete gui -l "delay"             -s "d"  -frk -d "Delay time in milliseconds"
-__flameshot_complete gui -l "region"                    -frk -d "Screenshot region to select (WxH+X+Y)" -a "(__flameshot_complete_region gui)"
-__flameshot_complete gui -l "last-region"               -f   -d "Repeat screenshot with previously selected region"
-__flameshot_complete gui -l "raw"               -s "r"  -f   -d "Print raw PNG capture"
-__flameshot_complete gui -l "print-geometry"    -s "g"  -f   -d "Print geometry of the selection"
-__flameshot_complete gui -l "upload"            -s "u"  -f   -d "Upload the screenshot"
-__flameshot_complete gui -l "pin"                       -f   -d "Pin the screenshot to the screen"
-__flameshot_complete gui -l "accept-on-select"  -s "s"  -f   -d "Accept capture as soon as a selection is made"
+__flameshot_complete gui --no-files
+__flameshot_complete gui --long-option "path"             --short-option "p" --description "Output file or directory"                          --require-parameter
+__flameshot_complete gui --long-option "clipboard"        --short-option "c" --description "Copy screenshot to the clipboard"                                      --no-files
+__flameshot_complete gui --long-option "delay"            --short-option "d" --description "Delay time in milliseconds"                        --require-parameter --no-files
+__flameshot_complete gui --long-option "region"                              --description "Screenshot region to select (WxH+X+Y)"             --require-parameter            --arguments "(__flameshot_complete_region gui)"
+__flameshot_complete gui --long-option "last-region"                         --description "Repeat screenshot with previously selected region"                     --no-files
+__flameshot_complete gui --long-option "raw"              --short-option "r" --description "Print raw PNG capture"                                                 --no-files
+__flameshot_complete gui --long-option "print-geometry"   --short-option "g" --description "Print geometry of the selection"                                       --no-files
+__flameshot_complete gui --long-option "upload"           --short-option "u" --description "Upload the screenshot"                                                 --no-files
+__flameshot_complete gui --long-option "pin"                                 --description "Pin the screenshot to the screen"                                      --no-files
+__flameshot_complete gui --long-option "accept-on-select" --short-option "s" --description "Accept capture as soon as a selection is made"                         --no-files
+__flameshot_complete gui --long-option "help"             --short-option "h" --description "Show the available arguments"                                          --no-files
 
 # SCREEN subcommand
-__flameshot_complete screen                             -f
-__flameshot_complete screen -l "number"         -s "n"  -frk -d "Screen number (starting from 0)" -a "(__flameshot_complete_screen_number)"
-__flameshot_complete screen -l "path"           -s "p"  -rk  -d "Output file or directory"
-__flameshot_complete screen -l "clipboard"      -s "c"  -f   -d "Copy screenshot to the clipboard"
-__flameshot_complete screen -l "delay"          -s "d"  -frk -d "Delay time in milliseconds"
-__flameshot_complete screen -l "region"                 -frk -d "Screenshot region to select (WxH+X+Y)" -a "(__flameshot_complete_region screen)"
-__flameshot_complete screen -l "last-region"            -f   -d "Repeat screenshot with previously selected region"
-__flameshot_complete screen -l "raw"            -s "r"  -f   -d "Print raw PNG capture"
-__flameshot_complete screen -l "upload"         -s "u"  -f   -d "Upload the screenshot"
-__flameshot_complete screen -l "pin"                    -f   -d "Pin the screenshot to the screen"
+__flameshot_complete screen --no-files
+__flameshot_complete screen --long-option "number"      --short-option "n" --description "Screen number (starting from 0)"                    --require-parameter --no-files --arguments "(__flameshot_complete_screen_number)"
+__flameshot_complete screen --long-option "path"        --short-option "p" --description "Output file or directory"                           --require-parameter
+__flameshot_complete screen --long-option "clipboard"   --short-option "c" --description "Copy screenshot to the clipboard"                                       --no-files
+__flameshot_complete screen --long-option "delay"       --short-option "d" --description "Delay time in milliseconds"                         --require-parameter --no-files
+__flameshot_complete screen --long-option "region"                          --description "Screenshot region to select (WxH+X+Y)"             --require-parameter --no-files --arguments "(__flameshot_complete_region screen)"
+__flameshot_complete screen --long-option "raw"         --short-option "r" --description "Print raw PNG capture"                                                 --no-files
+__flameshot_complete screen --long-option "upload"      --short-option "u" --description "Upload the screenshot"                                                 --no-files
+__flameshot_complete screen --long-option "pin"                            --description "Pin the screenshot to the screen"                                      --no-files
+__flameshot_complete screen --long-option "help"        --short-option "h" --description "Show the available arguments"                                          --no-files
 
 # FULL command
-__flameshot_complete full                               -f
-__flameshot_complete full   -l "path"           -s "p"  -rk  -d "Output file or directory"
-__flameshot_complete full   -l "clipboard"      -s "c"  -f   -d "Copy screenshot to the clipboard"
-__flameshot_complete full   -l "delay"          -s "d"  -frk -d "Delay time in milliseconds"
-__flameshot_complete full   -l "region"                 -frk -d "Screenshot region to select (WxH+X+Y)" -a "(__flameshot_complete_region full)"
-__flameshot_complete full   -l "last-region"            -f   -d "Repeat screenshot with previously selected region"
-__flameshot_complete full   -l "raw"            -s "r"  -f   -d "Print raw PNG capture"
-__flameshot_complete full   -l "upload"         -s "u"  -f   -d "Upload the screenshot"
-
-# LAUNCHER command doesn't have any completions specific to itself
-
-# CONFIG command -- TODO will be completed in a future version
-__flameshot_complete config                             -f
-__flameshot_complete config -l "check"                  -f   -d "Check the configuration for errors"
+__flameshot_complete full --no-files
+__flameshot_complete full --long-option "path"        --short-option "p" --description "Output file or directory"                          --require-parameter
+__flameshot_complete full --long-option "clipboard"   --short-option "c" --description "Copy screenshot to the clipboard"                                      --no-files
+__flameshot_complete full --long-option "delay"       --short-option "d" --description "Delay time in milliseconds"                        --require-parameter --no-files
+__flameshot_complete full --long-option "region"                         --description "Screenshot region to select (WxH+X+Y)"             --require-parameter --no-files --arguments "(__flameshot_complete_region full)" --keep-order
+__flameshot_complete full --long-option "raw"         --short-option "r" --description "Print raw PNG capture"                                                 --no-files
+__flameshot_complete full --long-option "upload"      --short-option "u" --description "Upload the screenshot"                                                 --no-files
+__flameshot_complete full --long-option "help"        --short-option "h" --description "Show the available arguments"                                          --no-files
+
+# LAUNCHER command
+__flameshot_complete launcher --no-files
+
+# CONFIG command
+__flameshot_complete config --no-files
+__flameshot_complete config --long-option "autostart"      --short-option "a" --description "Enable or disable run at startup"           --require-parameter --no-files --arguments "true false"
+__flameshot_complete config --long-option "filename"       --short-option "f" --description "Set the filename pattern"                   --require-parameter --no-files 
+__flameshot_complete config --long-option "notification"   --short-option "n" --description "Enable or disable the notification"         --require-parameter --no-files --arguments "true false"
+__flameshot_complete config --long-option "trayicon"       --short-option "t" --description "Enable or disable the tray icon"            --require-parameter --no-files --arguments "true false"
+__flameshot_complete config --long-option "showhelp"       --short-option "s" --description "Show the help message in the capture mode"  --require-parameter --no-files --arguments "true false"
+__flameshot_complete config --long-option "maincolor"      --short-option "m" --description "Define the main UI color (hexadecimal)"     --require-parameter --no-files 
+__flameshot_complete config --long-option "contrastcolor"  --short-option "k" --description "Define the contrast UI color (hexadecimal)" --require-parameter --no-files 
+__flameshot_complete config --long-option "check"                             --description "Check the configuration for errors"                             --no-files
+__flameshot_complete config --long-option "help"           --short-option "h" --description "Show the available arguments"                                   --no-files
diff --git a/data/shell-completion/flameshot.zsh b/data/shell-completion/flameshot.zsh
@@ -27,6 +27,7 @@ _flameshot_gui_opts=(
     {-u,--upload}'[Upload screenshot]'
     "--pin[Pin the capture to the screen]"
     {-s,--accept-on-select}'[Accept capture as soon as a selection is made]'
+    {-h,--help}'[Show the available arguments]'
 )
 
 _flameshot_gui() {
@@ -43,10 +44,10 @@ _flameshot_screen_opts=(
     {-c,--clipboard}'[Save the capture to the clipboard]'
     {-d,--delay}'[Delay time in milliseconds]'
     "--region[Screenshot region to select <WxH+X+Y or string>]"
-    "--last-region[Repeat screenshot with previously selected region]"
     {-r,--raw}'[Print raw PNG capture]'
     {-u,--upload}'[Upload screenshot]'
     "--pin[Pin the capture to the screen]"
+    {-h,--help}'[Show the available arguments]'
 )
 
 _flameshot_screen() {
@@ -62,9 +63,9 @@ _flameshot_full_opts=(
     {-c,--clipboard}'[Save the capture to the clipboard]'
     {-d,--delay}'[Delay time in milliseconds]'
     "--region[Screenshot region to select <WxH+X+Y or string>]"
-    "--last-region[Repeat screenshot with previously selected region]"
     {-r,--raw}'[Print raw PNG capture]'
     {-u,--upload}'[Upload screenshot]'
+    {-h,--help}'[Show the available arguments]'
 )
 
 _flameshot_full() {
@@ -76,13 +77,15 @@ _flameshot_full() {
 # config
 
 _flameshot_config_opts=(
-    {-a,--autostart}'[Enable or disable run at startup]'
+    {-a,--autostart}'[Enable or disable run at startup (true/false)]'
     {-f,--filename}'[Set the filename pattern]'
-    {-t,--trayicon}'[Enable or disable the tray icon]'
-    {-s,--showhelp}'[Define the main UI color]'
-    {-m,--maincolor}'[Show the help message in the capture mode]'
-    {-k,--contrastcolor}'[Define the contrast UI color]'
+    {-n,--notification}'[Enable or disable the notification (true/false)]'
+    {-t,--trayicon}'[Enable or disable the tray icon (true/false)]'
+    {-s,--showhelp}'[Show the help message in the capture mode (true/false)]'
+    {-m,--maincolor}'[Define the main UI color (hexadecimal)]'
+    {-k,--contrastcolor}'[Define the contrast UI color (hexadecimal)]'
     "--check[Check the configuration for errors]"
+    {-h,--help}'[Show the available arguments]'
 )
 
 _flameshot_config() {
@@ -97,7 +100,7 @@ _flameshot() {
     local -a state line commands
 
     commands=(
-        "gui:Start a manual capture in GUI mode"
+        "gui:Start the manual capture in GUI mode"
         "screen:Capture a single screen (one monitor)"
         "full:Capture the entire desktop (all monitors)"
         "launcher:Open the capture launcher"
