github.com/driusan/bug@v0.3.2-0.20190306121946-d7f4e7f33fea/bugapp/Help.go (about) 1 package bugapp 2 3 import ( 4 "fmt" 5 "os" 6 ) 7 8 func Help(args ...string) { 9 var cmd string 10 if args == nil { 11 cmd = "help" 12 13 } 14 if len(args) <= 1 { 15 cmd = "help" 16 } else { 17 cmd = args[1] 18 } 19 switch cmd { 20 case "create": 21 fmt.Printf("Usage: " + os.Args[0] + " create [-n] [options] Issue Title\n\n") 22 fmt.Printf( 23 `This will create an issue with the title Issue Title. An editor 24 will be opened automatically for you to enter a more detailed 25 description. If your EDITOR environment variable is set, it 26 will be used, otherwise the default editor is vim. 27 28 If the first argument to create is "-n", then %s will not open 29 any editor and create an empty Description. 30 31 Options take a value and set a field on the bug at the same 32 time as creating it. Valid options are: 33 --status Sets the bug status to the next parameter 34 --tag Tags the bug with a tag on creation 35 --priority Sets the priority to the next parameter 36 --milestone Sets the milestone to the next parameter 37 --identifier Sets the identifier to the next parameter 38 --generate-id Automatically generate a stable bug identifier 39 `, os.Args[0]) 40 case "list": 41 fmt.Printf("Usage: " + os.Args[0] + " list [BugIDs]\n") 42 fmt.Printf(" " + os.Args[0] + " list [tags]\n\n") 43 fmt.Printf( 44 `This will list the issues found in the current environment 45 46 With no arguments, titles will be printed to the screen along 47 with the issue number that can be used to reference this issue 48 on the command line. 49 50 If 1 or more BugIDs are provided, the whole issue including 51 description will be printed to STDOUT. See "bug help identifiers" 52 for a description of what makes a BugID. 53 54 If, instead of BugIDs, you provide list with 1 or more tags, 55 it will print any issues which have that tag (in short form). 56 57 Note that BugIDs may change as you create, edit, and close other 58 unless yo have defined a stable identifier for the issue. Again, 59 see "bug help identifiers." 60 61 The subcommand "view" is an alias for "list". 62 `) 63 64 case "edit": 65 fmt.Printf("Usage: " + os.Args[0] + " edit [Filename] BugID\n\n") 66 fmt.Printf( 67 `This will launch your standard editor to edit the description 68 of the bug identified by BugID. See "bug help identifiers" for a 69 description of what makes a BugID. 70 71 If the Filename option is provided, bug will instead launch an editor 72 to edit that file name within the bug directory. Files that have 73 special meaning to bug (Status, Milestone, Priority, Identifier) are 74 treated in a case insensitive manner, otherwise the filename is passed 75 directly to your editor. 76 `) 77 case "status": 78 fmt.Printf("Usage: " + os.Args[0] + " status BugID [NewStatus]\n\n") 79 fmt.Printf( 80 `This will edit or display the status of the bug identified by BugID. 81 See "bug help identifiers" for a description of what constitutes a BugID. 82 83 If NewStatus is provided, it will update the first line of the Status file 84 for the issue (creating the file as necessary). If not provided, it will 85 display the first line of the Status file to STDOUT. 86 87 Note that you can edit the status in your standard editor with the 88 command "%s edit status BugID". If you provide a longer than 1 line 89 status with "bug edit status", "bug status" will preserve everything 90 after the first line when editing a status. You can use this to provide 91 further context on a status (for instance, why that status is setup.) 92 `, os.Args[0]) 93 case "priority": 94 fmt.Printf("Usage: " + os.Args[0] + " priority BugID [NewPriority]\n\n") 95 fmt.Printf( 96 `This will edit or display the priority of BugID. See "bug help identifiers" 97 for a description of what constitutes a BugID. 98 99 By convention, priorities should be an integer number (higher is more 100 urgent), but that is not enforced by this command and NewPriority can 101 be any free-form text if you prefer. 102 103 If NewPriority is provided, it will update the first line of the Priority 104 file for the issue (creating the file as necessary). If not provided, it 105 will display the first line of the Priority file to STDOUT. 106 107 Note that you can manually edit the Priority file in the issues/ directory 108 by running "%s edit priority BugID", to provide further explanation (for 109 instance, why that priority is set.) This command will preserve the 110 explanation when updating a priority. 111 `, os.Args[0]) 112 case "milestone": 113 fmt.Printf("Usage: " + os.Args[0] + " milestone BugID [NewMilestone]\n\n") 114 fmt.Printf( 115 `This will edit or display the milestone of the identified by BugID. 116 See "%s help identifiers" for a description of what constitutes a BugID. 117 118 There are no restrictions on how milestones must be named, but 119 semantic versioning is a good convention to adopt. Failing that, 120 it's a good idea to use milestones that collate properly when 121 sorted as strings so that they appear properly in "%s roadmap". 122 123 If NewMilestone is provided, it will update the first line of the 124 Milestone file for the issue (creating the file as necessary). 125 If not provided, it will display the first line of the Milestone 126 file to STDOUT. 127 128 Note that you can manually edit the Milestone file in the issues/ 129 directory to provide further explanation (for instance, why that 130 milestone is set) with the command "bug edit milestone BugID" 131 132 This command will preserve the explanation when updating a priority. 133 `, os.Args[0], os.Args[0]) 134 case "retitle", "mv", "rename", "relabel": 135 fmt.Printf("Usage: " + os.Args[0] + " relabel BugID New Title\n\n") 136 fmt.Printf( 137 `This will change the title of BugID to "New Title". Use this 138 to rename an issue. 139 140 "%s mv", "%s retitle", and "%s rename" are all aliases for "%s relabel". 141 `, os.Args[0], os.Args[0], os.Args[0], os.Args[0]) 142 case "rm", "close": 143 fmt.Printf("Usage: " + os.Args[0] + " close BugID\n") 144 fmt.Printf(" " + os.Args[0] + " rm BugID\n\n") 145 fmt.Printf( 146 `This will delete the issue identifier by BugID. See 147 "%s help identifiers" for details on what constitutes a BugID. 148 149 Note that closing a bug may cause existing BugIDs to change if 150 they do not have a stable identifier set (see "%s help identifiers", 151 again.) 152 153 Also note that this does not remove the issue from git, but only 154 from the file system. You'll need to execute "bug commit" to 155 remove the bug from source control. 156 157 "%s rm" is an alias for this "%s close" 158 `, os.Args[0], os.Args[0], os.Args[0], os.Args[0]) 159 case "find": 160 fmt.Printf("Usage: %s find tag value1 [value2 ...]\n", os.Args[0]) 161 fmt.Printf("Usage: %s find status value1 [value2 ...]\n", os.Args[0]) 162 fmt.Printf("Usage: %s find priority value1 [value2 ...]\n", os.Args[0]) 163 fmt.Printf("Usage: %s find milestone value1 [value2 ...]\n\n", os.Args[0]) 164 fmt.Printf( 165 `This will search all bugs for multiple tags, statuses, priorities, or milestone. 166 The matching bugs will be printed. 167 `) 168 case "purge": 169 fmt.Printf("Usage: " + os.Args[0] + " purge\n\n") 170 fmt.Printf( 171 `This will delete any bugs that are not currently tracked by 172 git. 173 `) 174 case "commit": 175 fmt.Printf("Usage: " + os.Args[0] + " commit [--no-autoclose]\n\n") 176 fmt.Printf(`This will commit any new, modified, or removed issues to 177 git or hg. 178 179 Your working tree and staging area should be otherwise 180 unaffected by using this command. 181 182 If the --no-autoclose option is passed to commit, bug will 183 not include a "Closes #x" line for each issue imported from 184 "bug-import --github." Otherwise, the commit message will 185 include the list of issues that were closed so that GitHub 186 will autoclose them when the changes are pushed upstream. 187 `) 188 case "env": 189 fmt.Printf("Usage: " + os.Args[0] + " env\n\n") 190 fmt.Printf(`This will print the environment used by the bug command to stdout. 191 192 Use this command if you want to see what directory bug create is 193 using to store bugs, or what editor will be invoked by bug create/edit. 194 `) 195 196 case "dir", "pwd": 197 fmt.Printf("Usage: " + os.Args[0] + " dir\n\n") 198 fmt.Printf( 199 `This will print the undecorated bug directory to stdout, 200 so you can use it as a subcommand for arguments to any 201 arbitrary shell commands. For example "cd $(bug dir)" 202 203 "%s dir" is an alias for "%s pwd" 204 `, os.Args[0], os.Args[0]) 205 case "tag": 206 fmt.Printf("Usage: " + os.Args[0] + " tag [--rm] BugID [tags]\n\n") 207 fmt.Printf(`This will tag the given BugID with the tags 208 given as parameters. At least one tag is required. 209 210 Tags can be any string which would make a valid file name. 211 212 If the --rm option is provided before the BugID, all tags provided will 213 be removed instead of added. 214 `) 215 case "roadmap": 216 fmt.Printf("Usage: " + os.Args[0] + " roadmap [options]\n\n") 217 fmt.Printf( 218 `This will print a markdown formatted list of all open 219 issues, grouped by milestone. 220 221 Valid options are: 222 --simple Don't show anything other than the title in the output 223 --no-status Don't show the status of an issue 224 --no-priority Don't show the priority of an issue 225 --no-identifier Don't include the bug identifier of an issue 226 --tags Include the tags attached to a bug in it's output 227 228 --filter tag Only show bugs matching tag 229 --filter tag1,tag2,etc Only show issues matching at least one of 230 the supplied tags 231 232 `) 233 case "id", "identifier": 234 fmt.Printf("Usage: " + os.Args[0] + " identifier BugID [--generate] [value]\n\n") 235 fmt.Printf( 236 `This will either set of retrieve the identifier for the bug 237 currently identified by BugID. 238 239 If value is provided as an argument, the bug identifier will be set 240 to the value passed in. You should take care to ensure that any 241 identifier used has at least 1 non-numeric character, to ensure there 242 are no conflicts with automatically generated issue numbers used for 243 a bug that has no explicit identifier set. 244 245 If the --generate option is passed instead of a static value, a 246 short identifier will be generated derived from the issue's current 247 title (however, the identifier will remain unchanged if the bug's title 248 is changed.) 249 250 If only a BugID is provided, the current identifier will be printed. 251 252 "%s id" is an alias for "%s identifier" 253 `, os.Args[0], os.Args[0]) 254 case "about", "version": 255 fmt.Printf("Usage: " + os.Args[0] + " version\n\n") 256 fmt.Printf( 257 `This will print information about the version of %s being 258 invoked. 259 260 "%s about" is an alias for "version". 261 `, os.Args[0], os.Args[0]) 262 case "identifiers": 263 fmt.Printf( 264 `Bugs can be referenced in 2 ways on the commandline, either by 265 an index of where the bug directory is located inside the issues 266 directory, or by an identifier. "BugID" can be either of these, 267 and %s will try and intelligently guess which your command is 268 referencing. 269 270 By default, no identifiers are set for an issue. This means that 271 the issue number provided in "%s list" is an index into the directory, 272 and is unstable as bugs are created, modified, and closed. However, 273 the benefit is that they are easy to reference and remember, at least 274 in the short term. 275 276 If you have longer lasting issues that need a stable identifier, 277 they can be created by "%s identifier BugID NewIdentifier" to 278 set the identifier of BugID to NewIdentifier. From that point 279 forward, you can use NewIdentifier to reference the bug instead 280 of the directory index. 281 282 There are no rules for what constitutes a valid identifier, but 283 you should try and ensure that they have at least 1 non-numeric 284 character so that they don't conflict with directory indexes. 285 286 If you just want an identifier but don't care what it is, you 287 can use "%s identifier BugID --generate" to generate a new 288 identifier for BugID. 289 290 If there are no exact matches for the BugID provided, %s commands will 291 also try and look up the bug by a substring match on all the valid 292 identifiers in the system before giving up. 293 `, os.Args[0], os.Args[0], os.Args[0], os.Args[0], os.Args[0]) 294 295 case "help": 296 fallthrough 297 default: 298 fmt.Printf("Usage: " + os.Args[0] + " command [options]\n\n") 299 fmt.Printf("Use \"bug help [command]\" for more information about any command below\n\n") 300 fmt.Printf("Valid commands\n") 301 fmt.Printf("\nIssue editing commands:\n") 302 fmt.Printf("\tcreate\t File a new bug\n") 303 fmt.Printf("\tlist\t List existing bugs\n") 304 fmt.Printf("\tedit\t Edit an existing bug\n") 305 fmt.Printf("\ttag\t Tag a bug with a category\n") 306 fmt.Printf("\tidentifier Set a stable identifier for the bug\n") 307 fmt.Printf("\trelabel\t Rename the title of a bug\n") 308 fmt.Printf("\tclose\t Delete an existing bug\n") 309 fmt.Printf("\tstatus\t View or edit a bug's status\n") 310 fmt.Printf("\tpriority View or edit a bug's priority\n") 311 fmt.Printf("\tmilestone View or edit a bug's milestone\n") 312 fmt.Printf("\tfind\t Search bugs for a tag, status, priority, or milestone\n") 313 314 fmt.Printf("\nSource control commands:\n") 315 fmt.Printf("\tcommit\t Commit any new, changed or deleted bug to git\n") 316 fmt.Printf("\tpurge\t Remove all issues not tracked by git\n") 317 318 fmt.Printf("\nOther commands:\n") 319 fmt.Printf("\tenv\t Show settings that bug will use if invoked from this directory\n") 320 fmt.Printf("\tpwd\t Prints the issues directory to stdout (useful subcommand in the shell)\n") 321 fmt.Printf("\troadmap\t Print list of open issues sorted by milestone\n") 322 fmt.Printf("\tversion\t Print the version of this software\n") 323 fmt.Printf("\thelp\t Show this screen\n") 324 } 325 }