github.com/grantbow/fit@v0.7.1-0.20220916164603-1f7c88ac81e6/README.md (about) 1 # fit 2 filesystem issue tracker: manages plain text issues with git or hg 3 4 [](https://godoc.org/github.com/grantbow/fit) [](https://app.travis-ci.com/github/grantbow/fit) [](https://codecov.io/gh/grantbow/fit) [](https://goreportcard.com/report/github.com/grantbow/fit) [](https://bestpractices.coreinfrastructure.org/projects/2820) [](https://gitter.im/fit-issue/community) 5 6 **TOC:** 7 8 <!-- toc --> 9 10 - [Prerequisites](#prerequisites) 11 - [Goal](#goal) 12 - [Getting Started](#getting-started) 13 * [Layout](#layout) 14 * [Example Use](#example-use) 15 * [Installation](#installation) 16 * [Configuration](#configuration) 17 * [Example](#example) 18 - [Hooks](#hooks) 19 - [Governance](#governance) 20 - [Feedback](#feedback) 21 - [Next Steps](#next-steps) 22 23 <!-- tocstop --> 24 <!-- older topics 25 # fit init, fit open, fit close, fit archive, fit list 26 # what's an issue 27 # fit codecov, 3 x scan issues, 28 # fit summary 29 # characteristics 30 --> 31 32 ## Prerequisites 33 34 The only prerequisite is a filesystem. Issues can easily be created with new 35 directories and a text editor. 36 37 To list and manage the issues with the fit tool you need: 38 - git or hg (mercurial) 39 - go1.19 40 - any operating system [supported by go](https://go.dev/doc/install/source) and 41 [supported by 42 git](https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools) 43 including Windows, MacOS, Linux, \*BSD, Android, etc.. 44 45 ## Goal 46 47 Capture issues fast. 48 49 fit can be a project's primary issue system or a secondary system for code related issues. 50 51 Standard coding practices improve project outcomes. Using fit minimizes 52 switching between coding and issue tracking systems which increases 53 productivity and maintains code context. 54 55 The fit implementation is (almost) the simplest issue system that can still 56 work. The intent is to make fit conventions natural for users of 57 [git](https://en.wikipedia.org/wiki/Git) and 58 [golang](https://en.wikipedia.org/wiki/Go_(programming_language)). Contention 59 inherent in simpler issue systems is minimized and maintenance inherent in more 60 complex issue systems is avoided. See ([Background](#background)) for an 61 explanation. 62 63 ## Getting Started 64 65 ### Layout 66 67 Filesystem Issue Tracker conventions/format 68 ([Filesystem_Issues.md](docs/Filesystem_Issues.md)) store issues, one 69 directory/folder per issue, inside a "fit" directory. That document also 70 contains information about what a good issue looks like. Inside each issue 71 directory is a plain text "Description" file. 72 73 Optional tag\_<key>\_<value> files assign meta data. A minimal issue looks like: 74 75 fit/better_docs/Description 76 fit/better_docs/tag_id_1 77 78 The fit directory is located at the top of a git/mercurial repository and 79 subfolders may contain their own fit directory. 80 81 The config file is named `.fit.yml`, 82 83 The EDITOR environment variable is the editor used by default. 84 85 fit maintains the nearest `fit/` directory to your current working directory or 86 it's parent directories. 87 88 Setting an environment variable FIT overrides the default search for a location. 89 90 Unlike other issue systems, fit 91 issues naturally branch and merge along with the rest of your versioned files. 92 93 Some support is available to import and/or reference other issue trackers. 94 Usage reports via email or gitter are encouraged. 95 96 ### Example Use 97 98 To get started in the top of an existing git repo simply 99 `mkdir -p fit/<issue_name>` and edit `fit/<issue_name>/Description` with 100 your editor set in the EDITOR environment variable. 101 102 `fit list` shows your issues. 103 104 Add and commit the Description file like any other file in your repository. 105 106 `git add fit/<issue_name>/Description && git commit -m "first issue"` 107 108 If an environment variable named FIT is set that value will be used as a 109 directory name used to find the 'fit' or 'issues' directory instead of your 110 present working directory. All fit commands use the FIT environment variable 111 if present. 112 113 If a 'fit' directory/folder is not found and you enable recursion 114 fit will walk up your filesystem tree 115 until it finds a "fit" subdirectory similar to how git looks for 116 .git or hg looks for .hg. A warning is provided if no directory is found. 117 118 fit uses subcommands like git. For a list of commands use `fit help` 119 120 ### Installation 121 122 Briefly, you need git and [go installed](https://golang.org/doc/install). 123 124 `go install github.com/grantbow/fit@latest` 125 126 You can run fit as it's own command or as a git subcommand. 127 128 For details see ([INSTALL.md](INSTALL.md)). The software was developed with go1.13 but only the current and one previous version are supported before being declared [end of life](https://go.dev/doc/devel/release#policy). 129 130 ### Configuration 131 132 The environment variable EDITOR is used to execute your preferred editor 133 when needed. 134 135 Settings are read from .fit.yml next to the fit directory. 136 137 ``` 138 ClosePreventDelete: true 139 NewFieldAsTag: true 140 NewFieldLowerCase: true 141 IdAbbreviate: true 142 ``` 143 144 An important choice is what to do with closed issues. They can be deleted 145 (the historical default), moved to a subdirectory "closed" or 146 add a tag\_status\_closed which is recommended. 147 148 Current options include: 149 150 * DescriptionFileName: string 151 Default is "Description". 152 The name is one of the few imposed limitations. 153 This configuration allows overriding the name used in your system. 154 * DefaultDescriptionFile: string, 155 Default is "" 156 when doing fit {add|new|create} 157 first copy this file name to Description 158 recommended: fit/DescriptionDefault.txt 159 * ImportXmlDump: true or false, 160 Default is false. 161 during import, save raw xml files 162 * ImportCommentsTogether: true or false, 163 Default is false. 164 during import, commments save together as one file 165 instead of one comment per file. 166 * ProgramVersion: string 167 Default is "". Set to 0.6 when run. This 168 string is appended to identify local customizations. 169 * TagKeyValue: true or false 170 Default is false. 171 writes tags in tag_key_value format (true) 172 rather than .../tag/key without values. 173 tags in both forms are read automatically. 174 * NewFieldAsTag: true or false 175 Default is false. 176 writes fields in tag_key_value format (true) 177 rather than .../Key file with value in the text. 178 fields in both forms are read automatically. 179 * NewFieldLowerCase: true or false 180 Default is false. 181 writes fields as tag_key_value format (true) 182 rather than .../tag_Key_value. 183 fields in both forms are read automatically. 184 * GithubPersonalAccessToken: string 185 Default is empty. 186 Set one at github.com/settings/tokens 187 for import of private projects that need authentication 188 * TwilioAccountSid: string 189 Default is empty. 190 Needed for twilio use. 191 * TwilioAuthToken: string 192 Default is empty. 193 Needed for twilio use. 194 * TwilioPhoneNumberFrom: string 195 Default is empty. 196 Needed for twilio use. 197 * FitSite: string 198 Default is empty. 199 base url used in notifications 200 * MultipleDirs: true or false 201 Default is false. 202 Set to always look recursive. 203 * CloseStatusTag: true or false 204 Default is false. 205 fit close will not add a tag (false) or 206 add tag_status_closed (true) 207 * CloseMove: true or false 208 Default is false. 209 fit close will use ClosePreventDelete (false) or 210 fit close will move issues to CloseDir (true) and 211 sets ClosePreventDelete=true 212 * ClosedDirName: string 213 Default is "closed" 214 this is the name used inside the fit directory 215 * ClosePreventDelete: true or false 216 Default is false. 217 fit close will delete (false) or 218 fit close will not delete (true) 219 implies CloseStatusTag and/or CloseMove 220 * IdAbbreviate: true or false 221 Default is false. 222 Use Identifier. True uses Id. 223 * IdAutomatic: true or false 224 Default is false. 225 Generates an Identifier. 226 227 Other issue systems may use databases, hidden directories or hidden branches. 228 While these may be useful techniques in certain circumstances they obfuscate 229 access to the data. 230 231 Tags have been significantly enhanced since they were originally implemented. 232 Using the above options the default behavior of boolean present/not present 233 file names in a "tags" subdirectory can instead be filenames like Status that 234 contain the values or even simple tag\_key\_value filenames with empty contents 235 or comment contents. The last option enables great flexibility. A few keys are 236 hard coded in the program with special features: Identifier, Priority, Status, 237 Milestone and Tag. Newer tag\_key\_value filenames are recommended. 238 239 Comments and suggestions are welcomed. Pull requests are even better but are 240 not required to participate in this project. 241 242 ### Example 243 244 ``` 245 $ mkdir foo && cd foo 246 $ git init 247 $ mkdir fit 248 $ fit help 249 usage: fit help <command> 250 251 fit manages plain text issues with git or hg. 252 Use "fit help <command>" or "fit <command> help" for 253 more information about any command below. 254 fit version 0.7 built using go1.19 GOOS windows 255 executable: -rw-rw-rw- 8411136 Tue Sep 6 04:44:31 PDT 2022 fit.exe 256 257 Commands for status/reading: 258 list List issues 259 find Search for tag of fields: id, status, priority, or milestone 260 tagslist List assigned tags 261 notags List issues without tags 262 ids List stable identifiers 263 noids List issues without stable identifiers 264 env Show settings used when invoked from this directory 265 pwd Print the issues directory 266 help Show this screen 267 version Print the version of this software 268 269 Commands for editing: 270 create Open new issue 271 edit Edit an issue 272 retitle Rename an issue 273 close Delete an issue 274 tag Tag an issue 275 id View or set a stable identifier 276 status View or set status 277 priority View or set priority 278 milestone View or set milestone 279 import Download from github or bugseverywhere repository 280 281 Commands for version control: 282 commit Commit any new, changed or deleted issues 283 purge Remove all issues not tracked 284 285 Commands for processing: 286 roadmap Print list of open issues sorted by milestone 287 288 aliases for help: --help -h 289 290 $ fit create better docs 291 (<your editor> Description) 292 (save and quit) 293 Created issue: better docs 294 295 $ fit list 296 297 ===== list /.../foo/fit 298 Issue 1: better docs 299 300 $ fit list 1 301 302 ===== list /.../foo/fit 303 Title: better docs 304 Description: 305 <the entered description> 306 307 $ fit create -n better README formatting 308 (no editor launched, defaults to empty Description file) 309 Created issue: better README formatting 310 311 $ fit list 312 313 ===== list /.../foo/fit 314 Issue 1: better help 315 Issue 2: better README formatting 316 ``` 317 318 ## Hooks 319 320 Event based automation can be added through git or mercurial hooks. Our hooks 321 directory contains some examples. We look forward to seeing what teams use and 322 contribute. Adapting hooks to both git and hg would be appreciated. 323 324 ## Governance 325 326 There are two key roles in the fit project: project owner & lead contributors. 327 Collaboration is encouraged. See docs/FAQ.md for details. 328 329 ## Feedback 330 331 We would very much like to hear about how you use this system. 332 333 I would like to work with others and would appreciate feedback at 334 grantbow+fit@gmail.com. 335 336 Since the original bug project is not very active I have gone ahead and continuted 337 development. I encourage discussion. Submissions can be done with a 338 pull request or using [git remotes](https://stackoverflow.com/questions/36628859/git-how-to-merge-a-pull-request-into-a-fork). 339 340 ## Next Steps 341 342 * docs/[Filesystem_Issues.md](docs/Filesystem_Issues.md) 343 * docs/[FAQ.md](docs/FAQ.md) 344 * docs/[Background.md](Background.md) 345 * [CONTRIBUTING.md](CONTRIBUTING.md) 346 * [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) is the standard recommended by github offered by contributor-covenant.org. 347 * [SUPPORT.md](SUPPORT.md) 348 * [wiki](https://github.com/grantbow/fit/wiki) 349 * [gitter](https://gitter.im/fit-issue/community) 350 * [SECURITY.md](SECURITY.md) 351 352 Your system is just the beginning, not the end. Much has been written about 353 how to use and setup systems to track or manage issues, software bugs, trouble 354 tickets, support tickets, incident tickets or requests. See the docs/FAQ.md 355