{"id":37157051,"url":"https://github.com/grantbow/fit","last_synced_at":"2026-01-14T18:41:16.068Z","repository":{"id":57514083,"uuid":"224132354","full_name":"grantbow/fit","owner":"grantbow","description":"filesystem issue tracker: manages plain text issues with git or mercurial","archived":false,"fork":false,"pushed_at":"2023-02-23T23:59:25.000Z","size":858,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-06-20T01:56:37.968Z","etag":null,"topics":["filesystem-issue-tracker","git","golang","mercurial"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grantbow.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-26T07:46:27.000Z","updated_at":"2023-03-05T00:28:11.000Z","dependencies_parsed_at":"2024-06-20T01:41:32.638Z","dependency_job_id":null,"html_url":"https://github.com/grantbow/fit","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/grantbow/fit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantbow%2Ffit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantbow%2Ffit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantbow%2Ffit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantbow%2Ffit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grantbow","download_url":"https://codeload.github.com/grantbow/fit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grantbow%2Ffit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28430880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T16:38:47.836Z","status":"ssl_error","status_checked_at":"2026-01-14T16:34:59.695Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["filesystem-issue-tracker","git","golang","mercurial"],"created_at":"2026-01-14T18:41:15.491Z","updated_at":"2026-01-14T18:41:16.060Z","avatar_url":"https://github.com/grantbow.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fit\nfilesystem issue tracker: manages plain text issues with git or hg \n\n[![GoDoc](https://godoc.org/github.com/grantbow/fit?status.svg)](https://godoc.org/github.com/grantbow/fit) [![Build Status](https://travis-ci.com/grantbow/fit.svg?branch=master)](https://app.travis-ci.com/github/grantbow/fit) [![Test Coverage](https://codecov.io/gh/grantbow/fit/branch/master/graphs/badge.svg)](https://codecov.io/gh/grantbow/fit) [![GoReportCard](https://goreportcard.com/badge/github.com/grantbow/fit)](https://goreportcard.com/report/github.com/grantbow/fit) [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/2820/badge)](https://bestpractices.coreinfrastructure.org/projects/2820) [![Gitter chat](https://badges.gitter.im/gitterHQ/gitter.png)](https://gitter.im/fit-issue/community)\n\n**TOC:**\n\n\u003c!-- toc --\u003e\n\n- [Prerequisites](#prerequisites)\n- [Goal](#goal)\n- [Getting Started](#getting-started)\n  * [Layout](#layout)\n  * [Example Use](#example-use)\n  * [Installation](#installation)\n  * [Configuration](#configuration)\n  * [Example](#example)\n- [Hooks](#hooks)\n- [Governance](#governance)\n- [Feedback](#feedback)\n- [Next Steps](#next-steps)\n\n\u003c!-- tocstop --\u003e\n\u003c!-- older topics\n# fit init, fit open, fit close, fit archive, fit list\n# what's an issue\n# fit codecov, 3 x scan issues,\n# fit summary\n# characteristics\n--\u003e\n\n## Prerequisites\n\nThe only prerequisite is a filesystem. Issues can easily be created with new\ndirectories and a text editor.\n\nTo list and manage the issues with the fit tool you need:\n- git or hg (mercurial)\n- go1.19\n- any operating system [supported by go](https://go.dev/doc/install/source) and\n  [supported by\n  git](https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools)\n  including Windows, MacOS, Linux, \\*BSD, Android, etc..\n\n## Goal\n\nCapture issues fast.\n\nfit can be a project's primary issue system or a secondary system for code related issues.\n\nStandard coding practices improve project outcomes. Using fit minimizes\nswitching between coding and issue tracking systems which increases\nproductivity and maintains code context.\n\nThe fit implementation is (almost) the simplest issue system that can still\nwork. The intent is to make fit conventions natural for users of\n[git](https://en.wikipedia.org/wiki/Git) and\n[golang](https://en.wikipedia.org/wiki/Go_(programming_language)). Contention\ninherent in simpler issue systems is minimized and maintenance inherent in more\ncomplex issue systems is avoided. See ([Background](#background)) for an\nexplanation.\n\n## Getting Started\n\n### Layout\n\nFilesystem Issue Tracker conventions/format\n([Filesystem_Issues.md](docs/Filesystem_Issues.md)) store issues, one\ndirectory/folder per issue, inside a \"fit\" directory. That document also\ncontains information about what a good issue looks like. Inside each issue\ndirectory is a plain text \"Description\" file. \n\nOptional tag\\_\u003ckey\u003e\\_\u003cvalue\u003e files assign meta data. A minimal issue looks like:\n\n    fit/better_docs/Description\n    fit/better_docs/tag_id_1\n\nThe fit directory is located at the top of a git/mercurial repository and\nsubfolders may contain their own fit directory.\n\nThe config file is named `.fit.yml`,\n\nThe EDITOR environment variable is the editor used by default.\n\nfit maintains the nearest `fit/` directory to your current working directory or\nit's parent directories.\n\nSetting an environment variable FIT overrides the default search for a location.\n\nUnlike other issue systems, fit\nissues naturally branch and merge along with the rest of your versioned files.\n\nSome support is available to import and/or reference other issue trackers.\nUsage reports via email or gitter are encouraged.\n\n### Example Use\n\nTo get started in the top of an existing git repo simply\n`mkdir -p fit/\u003cissue_name\u003e` and edit `fit/\u003cissue_name\u003e/Description` with\nyour editor set in the EDITOR environment variable.\n\n`fit list` shows your issues.\n\nAdd and commit the Description file like any other file in your repository.\n\n`git add fit/\u003cissue_name\u003e/Description \u0026\u0026 git commit -m \"first issue\"`\n\nIf an environment variable named FIT is set that value will be used as a\ndirectory name used to find the 'fit' or 'issues' directory instead of your\npresent working directory. All fit commands use the FIT environment variable\nif present.\n\nIf a 'fit' directory/folder is not found and you enable recursion\nfit will walk up your filesystem tree\nuntil it finds a \"fit\" subdirectory similar to how git looks for\n.git or hg looks for .hg. A warning is provided if no directory is found.\n\nfit uses subcommands like git. For a list of commands use `fit help`\n\n### Installation\n\nBriefly, you need git and [go installed](https://golang.org/doc/install).\n\n`go install github.com/grantbow/fit@latest`\n\nYou can run fit as it's own command or as a git subcommand.\n\nFor 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).\n\n### Configuration\n\nThe environment variable EDITOR is used to execute your preferred editor\nwhen needed.\n\nSettings are read from .fit.yml next to the fit directory.\n\n```\nClosePreventDelete: true\nNewFieldAsTag: true\nNewFieldLowerCase: true\nIdAbbreviate: true\n```\n\nAn important choice is what to do with closed issues. They can be deleted\n(the historical default), moved to a subdirectory \"closed\" or\nadd a tag\\_status\\_closed which is recommended.\n\nCurrent options include:\n\n    * DescriptionFileName: string\n          Default is \"Description\".\n          The name is one of the few imposed limitations.\n          This configuration allows overriding the name used in your system.\n    * DefaultDescriptionFile: string,\n          Default is \"\"\n          when doing fit {add|new|create}\n          first copy this file name to Description\n          recommended: fit/DescriptionDefault.txt\n    * ImportXmlDump: true or false, \n          Default is false.\n          during import, save raw xml files\n    * ImportCommentsTogether: true or false,\n          Default is false.\n          during import, commments save together as one file\n          instead of one comment per file.\n    * ProgramVersion: string\n          Default is \"\". Set to 0.6 when run. This\n          string is appended to identify local customizations.\n    * TagKeyValue: true or false\n          Default is false.\n          writes tags in tag_key_value format (true)\n          rather than .../tag/key without values.\n          tags in both forms are read automatically.\n    * NewFieldAsTag: true or false\n          Default is false.\n          writes fields in tag_key_value format (true)\n          rather than .../Key file with value in the text.\n          fields in both forms are read automatically.\n    * NewFieldLowerCase: true or false\n          Default is false.\n          writes fields as tag_key_value format (true)\n          rather than .../tag_Key_value.\n          fields in both forms are read automatically.\n    * GithubPersonalAccessToken: string\n          Default is empty.\n          Set one at github.com/settings/tokens\n          for import of private projects that need authentication\n    * TwilioAccountSid: string\n          Default is empty.\n          Needed for twilio use.\n    * TwilioAuthToken: string\n          Default is empty.\n          Needed for twilio use.\n    * TwilioPhoneNumberFrom: string\n          Default is empty.\n          Needed for twilio use.\n    * FitSite: string\n          Default is empty.\n          base url used in notifications\n    * MultipleDirs: true or false\n          Default is false.\n          Set to always look recursive.\n    * CloseStatusTag: true or false\n          Default is false.\n          fit close will not add a tag (false) or\n          add tag_status_closed (true)\n    * CloseMove: true or false\n          Default is false.\n          fit close will use ClosePreventDelete (false) or\n          fit close will move issues to CloseDir (true) and\n              sets ClosePreventDelete=true\n    * ClosedDirName: string\n          Default is \"closed\"\n          this is the name used inside the fit directory\n    * ClosePreventDelete: true or false\n          Default is false.\n          fit close will delete (false) or\n          fit close will not delete (true)\n              implies CloseStatusTag and/or CloseMove\n    * IdAbbreviate: true or false\n          Default is false.\n          Use Identifier. True uses Id.\n    * IdAutomatic: true or false\n          Default is false.\n          Generates an Identifier.\n\nOther issue systems may use databases, hidden directories or hidden branches.\nWhile these may be useful techniques in certain circumstances they obfuscate\naccess to the data.\n\nTags have been significantly enhanced since they were originally implemented.\nUsing the above options the default behavior of boolean present/not present\nfile names in a \"tags\" subdirectory can instead be filenames like Status that\ncontain the values or even simple tag\\_key\\_value filenames with empty contents\nor comment contents. The last option enables great flexibility. A few keys are\nhard coded in the program with special features: Identifier, Priority, Status,\nMilestone and Tag. Newer tag\\_key\\_value filenames are recommended.\n\nComments and suggestions are welcomed. Pull requests are even better but are\nnot required to participate in this project.\n\n### Example\n\n```\n$ mkdir foo \u0026\u0026 cd foo\n$ git init\n$ mkdir fit\n$ fit help\nusage: fit help \u003ccommand\u003e\n\nfit manages plain text issues with git or hg.\nUse \"fit help \u003ccommand\u003e\" or \"fit \u003ccommand\u003e help\" for\n    more information about any command below.\nfit version 0.7 built using go1.19 GOOS windows\nexecutable: -rw-rw-rw- 8411136 Tue Sep  6 04:44:31 PDT 2022 fit.exe\n\nCommands for status/reading:\n    list       List issues\n    find       Search for tag of fields: id, status, priority, or milestone\n    tagslist   List assigned tags\n    notags     List issues without tags\n    ids        List stable identifiers\n    noids      List issues without stable identifiers\n    env        Show settings used when invoked from this directory\n    pwd        Print the issues directory\n    help       Show this screen\n    version    Print the version of this software\n\nCommands for editing:\n    create     Open new issue\n    edit       Edit an issue\n    retitle    Rename an issue\n    close      Delete an issue\n    tag        Tag an issue\n    id         View or set a stable identifier\n    status     View or set status\n    priority   View or set priority\n    milestone  View or set milestone\n    import     Download from github or bugseverywhere repository\n\nCommands for version control:\n    commit     Commit any new, changed or deleted issues\n    purge      Remove all issues not tracked\n\nCommands for processing:\n    roadmap    Print list of open issues sorted by milestone\n\naliases for help: --help -h\n\n$ fit create better docs\n(\u003cyour editor\u003e Description)\n(save and quit)\nCreated issue: better docs\n\n$ fit list\n\n===== list /.../foo/fit\nIssue 1: better docs\n\n$ fit list 1\n\n===== list /.../foo/fit\nTitle: better docs\nDescription:\n\u003cthe entered description\u003e\n\n$ fit create -n better README formatting\n(no editor launched, defaults to empty Description file)\nCreated issue: better README formatting\n\n$ fit list\n\n===== list /.../foo/fit\nIssue 1: better help\nIssue 2: better README formatting\n```\n\n## Hooks\n\nEvent based automation can be added through git or mercurial hooks. Our hooks\ndirectory contains some examples. We look forward to seeing what teams use and\ncontribute. Adapting hooks to both git and hg would be appreciated.\n\n## Governance\n\nThere are two key roles in the fit project: project owner \u0026 lead contributors.\nCollaboration is encouraged. See docs/FAQ.md for details.\n\n## Feedback\n\nWe would very much like to hear about how you use this system.\n\nI would like to work with others and would appreciate feedback at\ngrantbow+fit@gmail.com.\n\nSince the original bug project is not very active I have gone ahead and continuted\ndevelopment. I encourage discussion. Submissions can be done with a\npull request or using [git remotes](https://stackoverflow.com/questions/36628859/git-how-to-merge-a-pull-request-into-a-fork).\n\n## Next Steps\n\n* docs/[Filesystem_Issues.md](docs/Filesystem_Issues.md)\n* docs/[FAQ.md](docs/FAQ.md)\n* docs/[Background.md](Background.md)\n* [CONTRIBUTING.md](CONTRIBUTING.md)\n* [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) is the standard recommended by github offered by contributor-covenant.org.\n* [SUPPORT.md](SUPPORT.md)\n* [wiki](https://github.com/grantbow/fit/wiki)\n* [gitter](https://gitter.im/fit-issue/community)\n* [SECURITY.md](SECURITY.md)\n\nYour system is just the beginning, not the end. Much has been written about\nhow to use and setup systems to track or manage issues, software bugs, trouble\ntickets, support tickets, incident tickets or requests. See the docs/FAQ.md\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantbow%2Ffit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrantbow%2Ffit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrantbow%2Ffit/lists"}