{"id":13558631,"url":"https://github.com/mgoellnitz/trackdown","last_synced_at":"2025-04-03T13:31:47.810Z","repository":{"id":50736700,"uuid":"48142366","full_name":"mgoellnitz/trackdown","owner":"mgoellnitz","description":"TrackDown - Issue Tracking with plain Markdown. If you are missing the \"git clone\" for your tickets from github.com, codeberg.org, or gitlab.com, then this is for you. A lightweight Ticketing System for distributed and unconnected small Teams.","archived":false,"fork":false,"pushed_at":"2025-01-16T00:55:49.000Z","size":495,"stargazers_count":29,"open_issues_count":0,"forks_count":4,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-01-16T01:28:44.662Z","etag":null,"topics":["bitbucket","gitlab","issue-tracker","markdown","mercurial","ticket","wiki"],"latest_commit_sha":null,"homepage":"http://mgoellnitz.github.io/trackdown","language":"Shell","has_issues":false,"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/mgoellnitz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"ko_fi":"backendzeit"}},"created_at":"2015-12-17T00:12:30.000Z","updated_at":"2025-01-16T00:55:50.000Z","dependencies_parsed_at":"2024-01-08T02:29:09.146Z","dependency_job_id":"3eb50138-976e-4f9f-9685-9645ebfda73d","html_url":"https://github.com/mgoellnitz/trackdown","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoellnitz%2Ftrackdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoellnitz%2Ftrackdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoellnitz%2Ftrackdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mgoellnitz%2Ftrackdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mgoellnitz","download_url":"https://codeload.github.com/mgoellnitz/trackdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247009661,"owners_count":20868588,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["bitbucket","gitlab","issue-tracker","markdown","mercurial","ticket","wiki"],"created_at":"2024-08-01T12:05:04.271Z","updated_at":"2025-04-03T13:31:47.496Z","avatar_url":"https://github.com/mgoellnitz.png","language":"Shell","funding_links":["https://ko-fi.com/backendzeit","https://ko-fi.com/L4L5T3APO"],"categories":["Shell","markdown"],"sub_categories":[],"readme":"# TrackDown\n\n[![Latest Release](https://img.shields.io/github/release/mgoellnitz/trackdown.svg)](https://github.com/mgoellnitz/trackdown/releases/latest)\n[![License](https://img.shields.io/github/license/mgoellnitz/trackdown.svg)](https://github.com/mgoellnitz/trackdown/blob/master/LICENSE)\n[![Build](https://img.shields.io/gitlab/pipeline/mgoellnitz/trackdown.svg)](https://gitlab.com/mgoellnitz/trackdown/pipelines)\n[![Download](https://img.shields.io/badge/Download-Snapshot-blue)](https://gitlab.com/mgoellnitz/trackdown/-/jobs/artifacts/master/download?job=trackdown)\n\nIssue Tracking with plain [Markdown][markdown] for [GIT][git] and\n[Mercurial][hg].\n\nIn short: You are missing the `git clone` or `hg clone` respectively for your\ntickets from [Codeberg][codeberg], [GitLab][gitlab], [GitHub][github], or some\nother services (see below) where we already have this for code and wiki?\n\nYou need issue tracking which works for distributed and potentially disconnected\nsituations together with your distributed version control [GIT][git] or\n[Mercurial][hg] and e.g. also your distributed wiki editing through [GIT][git]\nor [Mercurial][hg] as well?\n\nThen this here is for you!\n\n[Support this project](https://ko-fi.com/backendzeit):\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L4L5T3APO)\n\nIt is not intended for large, permanently online or connected teams and heavy\nflows of tickets though, since you will be having only one file with plain\n[Markdown][markdown] with your issues - and optionally other stuff - collected\nin it.\n\nThe currently open issues of TrackDown itself can be found\n[here](https://codeberg.org/backendzeit/trackdown/src/branch/trackdown/issues.md),\n[here](https://gitlab.com/mgoellnitz/trackdown/blob/trackdown/issues.md), and\n[here](https://github.com/mgoellnitz/trackdown/blob/trackdown/issues.md).\n\nThe corresponding roadmap is placed\n[here](https://codeberg.org/backendzeit/trackdown/src/branch/trackdown/roadmap.md),\n[here](https://gitlab.com/mgoellnitz/trackdown/blob/trackdown/roadmap.md), and\n[here](https://github.com/mgoellnitz/trackdown/blob/trackdown/roadmap.md).\n\n\n## Feedback\n\nThe primary home of this project for contribution and feedback lives at\n[Codeberg][codeberg] with additional mirrors at [GitLab][gitlab] and\n[GitHub][github].\n\n\n# Design\n\nWhile TrackDown does not define an issue related workflow, it has some intended\nworkflow elements which are supported:\n\nThe issues are defined and maintained in a single [Markdown][markdown] file\nfollowing the format given here.\n\nThe [GIT][git] post-commit hook or [Mercurial][hg] commit hook of TrackDown\nreads the commit messages and  modifies that issue collection if your commit\nmessages relate to some of the  issues.\n\nAdditionally, a roadmap file is automatically maintained for your tickets.\nThis roadmap file groups the issue's headlines in groups according to their\nversion label and illustrated progress counting issues in progress and resolved\nissues.\n\nThe issue collection this way is held local on your machine and not remote in\nthe database of a tracking system. (Which is something also [Fossil][fossil]\nsupports.) Like with the source code, it is pushed to remote repositories if\nneeded (or possible). The simple [Markdown][markdown] format and the usage of\n[GIT][git] or [Mercurial][hg] as a backend support distributed, shared editing\nand later merging of the issues and the related notes in the issue collection.\n(This is where the  parallel with [Fossil][fossil] ends).\n\n\n# The Format\n\nWhile sticking to only partly structured [Markdown][markdown] the following\nelements should be maintainable with TrackDown:\n\n- ID\n- Title\n- Status\n- Commits\n- Target Version\n- Severity\n- Affected Versions\n- Description\n- Comments\n\nThese fields are mapped to the following source structure\n\n```\n  ## ID Title (status)\n\n  *Target Version (optional)* - Currently assigned to: `me` (optional)\n\n  ### severity (optional) priority (optional)\n\n  affected versions: 1.0, 1.1 (optional)\n\n  ### Description (optional)\n\n  description\n\n  ### Comments (optional)\n\n  comments (structured)\n\n  ### Commits (auto generated)\n\n  The headline commits at level three is optional. The commit messages are\n  inserted just as the last part of the issue's level two text area.\n```\n\nThe really fixed non-optional parts of this are\n\n```\n  ## ID Title (status)\n\n  (Commit messages inserted here before the next ticket)\n```\n\n\n## Field Values\n\n### ID\n\nAny combination of (English) upper- and lower-case letters and digits.\n\n### Title\n\nAny expressible in Markdown.\n\n### Status\n\nAnything expressible in Markdown. Automatically set values are \"in progress\" if\nyou start committing for a certain ID and \"resolved\", if you are using a prefix\nof \"fixes ID\" or \"resolves ID\".\n\nOther intended values include \"new\", where the issue is just files, and \"closed\"\nwhen the solution is brought into production.\n\n### Target Version\n\nOnly digits, letters and dots. No spaces allowed.\n\n### Description\n\nAnything expressible in Markdown.\n\n### Affected Versions\n\nAnything expressible in Markdown. Is expected to describe which version are\naffected by the issue (if this is possible to say).\n\n### Comments\n\nAnything expressible in Markdown.\n\n### Severity\n\nAnything expressible in Markdown.\n\n\n# Setup\n\nThere are two ways to set up TrackDown: Have the issues file integrated in your\nsource code repository, or place it in an arbitrary place of your choosing.\n\nThe first - default - way is to use it in a separate branch of your source code\nrepository. It is kept visible and editable through a symbolic link at the\nroot level of the source code repository. Of course, this file is touched\nautomatically via commits to your source code through the (post-)commit hook of\nTrackDown.\n\nThe second way is to use the file at a different location - e.g. in the wiki of\nthe project instead of the source code repository, which is described later.\n\nIn both cases, the automatically maintained roadmap file resides next to the\nissue collection file.\n\n\n## Initialize the Repository\n\nIf you want to track the issues in a TrackDown branch of your source code\nrepository and not in any other location of your choosing, you need to modify the\n[GIT][git] or [Mercurial][hg] repository accordingly. Your source code\nrepository must contain at least one commit for this to work.\n\nTo initialize your source code repository this way, call the script\n\n```\ntrackdown.sh init\n```\n\nThis creates the TrackDown branch for the issue tracking. For [GIT][git]\nrepositories, you have to manually propagate this thread to your upstream\nrepositories.\n\n```\ngit push origin trackdown\n```\n\nTrackDown does not interfere with your remote workflow for any version control\nsystem: Also for [Mercurial][hg] the trackdown branch will only show up in the\nremote repositories if you push it.\n\n```\nhg push\n```\n\nInitialization must only be executed once for a repository including all of its\nforks and clones.\n\nIf you want to use the issue collection file from a different location than the\nspecial TrackDown branch, leave out this step.\n\n\n## Repository Integration\n\nRegardless of the location of the issue collection file, for each clone of the\nrepository you have to set up the TrackDown tooling to be able to use it\nintegrated with your source code commits.\n\nTo start using TrackDown for the respective clone, you have to issue\n\n```\ntrackdown.sh use\n```\n\nwhen using the TrackDown branch in the source code repository or\n\n```\ntrackdown.sh use \u003cpath/to/issues.md\u003e\n```\n\nlike in\n\n```\ntrackdown.sh use ../wiki/issues.md\n```\n\nwhen using TrackDown with the issue collection file at a different location.\nAutomatic commit and push (see below) will be switched off in the latter case.\n\nThis creates (git or hg ignored) links `issues.md` and `roadmap.md` in the root\ndirectory of your project pointing to the issue collection file and the roadmap.\nAdditionally, it will configure a post-commit hook for [GIT][git] or a commit\nhook for [Mercurial][hg] respectively.\n\nAfter this step, you can edit the issue collection file following the format\nmentioned above.\n\n\n# Commands in the Commit Messages\n\nTrackDown is supposed to read the commit messages when not used as a plain\nmirror and interpret the contents as potential commands for the modification of\nalongside you work.\n\nWhen using [GIT][git], TrackDown relies on an implementation, which is capable\nof executing the script hooks, which is - as opposed to [Mercurial][hg] - not\nthe case for all implementations.\n\nRight now, TrackDown understands only two commands in the commit messages.\n\n\n## refs #*id*[,*id*...]\n\nReference the commit in the list of commits at the end of the issue text.\n\n```\ngit commit -m \"refs #MYID - comment\" files...\n```\n\nThis command changes the state to \"in progress\" from anything like new, nothing,\nor even resolved. If the commit relates to more than one issue, the issues can\nbe separated by commas.\n\n```\ngit commit -m \"fixes #ONEID,ANOTHERID - comment\" files...\n```\n\n```\n(Future work: lifts the issue up to the top of the list)\n```\n\n\n## resolves|resolve|fixes #*id*[,*id*...]\n\nReference the commit in the list of commits at the end of the issue text.\n\n```\ngit commit -m \"fixes #MYID - comment\" files...\n```\n\nThis command changes the state to \"resolved\" from anything like new, nothing, or\nin progress. If the commit relates to more than one issue, the issues can be\nseparated by commas.\n\n```\ngit commit -m \"fixes #ONEID,ANOTHERID - comment\" files...\n```\n\n```\n(Future work: moves the issue to the top the part of the list where the resolved issues reside)\n```\n\n\n# Command Line Tools\n\nIn addition to the init and integration tools, the following commands are\navailable:\n\n\n## Roadmap\n\nProvided that the issues in the issue collection file are marked with version\nlabels like suggested, the command\n\n```\ntrackdown.sh roadmap\n```\n\nprints out a complete roadmap of the project sorted by \"target versions\" in\n[Markdown][markdown] format.\n\nThe term \"target version\" could also be read as \"release\" or \"sprint\" or\nanything which describes your development process best.\n\n\n## List\n\nThe command `ls` is used to show all issues marked for a given \"target version\"\nlike in\n\n```\ntrackdown.sh ls 1.1\n```\n\nwhere all issues intended to be completed in \"target version\" 1.1 are listed.\n\nThe term \"target version\" could also be read as \"release\" or \"sprint\" or\nanything which describes your development process best.\n\n\n## My Tickets\n\nThe command\n\n```\ntrackdown.sh mine\n```\n\nlists all issues in the issue collection, which are marked with a\n\n```\n*Version 1.0* - Currently assigned to: `me`\n```\n\nThe `me` placeholder in the case is taken - in that order - from\n\n* the first parameter on the command line\n* The `me` entry in the `.trackdown/config` file\n* The local user name from the environment variable `$USER`\n\nOptionally, you can add a path to an issue collection file as an additional parameter\nlike in\n\n```\ntrackdown.sh mine ../wiki/issues.md\n```\n\nor\n\n```\ntrackdown.sh mine UserName ../wiki/issues.md\n```\n\n\n## Show Issue Collection Changes Status\n\nTo show the current state of the local editing of the issue collection and\nroadmap file, even if they reside in a special TrackDown branch and are only\nused as symbolic links in the source code repository, a shortcut command is\navailable, giving a brief summary of the Mercurial or GIT state if the\nissue collection and roadmap file.\n\n```\ntrackdown.sh status\n```\n\n\n## Quick Sync of Issue Collection and Roadmap\n\nMost times the editing changelog of the issue collection file and roadmap file\ndon't present too much additional information for which is already held in\nthe commit messages of the source code and the issue collection file itself.\n\nIn such situations, you can use the shortcut command `sync` to bring the\nissue collection and roadmap file on your machine and the remote repository\nin sync.\n\n```\ntrackdown.sh sync\n```\n\n\n## Copy Milestone/Release Contents\n\nThe command `copy` is used to extract the issues related to a given milestone,\nrelease, version, or whatever your terminology might be to a separate file\nnamed after the given parameter. So\n\n```\ntrackdown.sh copy 1.1\n```\n\ncopies all notes for the issues marked with \"1.1\" as a version marker to a\nseparate file 1.1.md to obtain release notes and get the resolved issues from\nthe base issue collection file for your current work.\n\n\n## Issues\n\nThe command\n\n```\ntrackdown.sh issues\n```\n\nlists all potential issues in the issue collection. Potential means in this\ncase, that there may be some false positives if there are additional elements\nin your issue collection file, which might be interpreted as issues.\n\nOptionally, you can add a path to an issue collection file as a parameter, like\nin\n\n```\ntrackdown.sh issues ../wiki/issues.md\n```\n\n\n# Configuration\n\nThe source repository contains a directory named `.trackdown/`.\n\nThis directory contains a file named `config`. There are some options in this\nfile, which you might want to change.\n\nExample config file for TrackDown:\n\n```\n  autocommit=true\n  autopush=false\n  location=../wiki/issues.md\n  prefix=https://github.com/user/project/commit/\n  me=My Name\n```\n\n\n## Auto Commit all Issue Collection Changes\n\nAutomatically commits the new change to the TrackDown branch. If you didn't\nchange the default location where your source code repository contains the\na TrackDown branch, you will want to leave the unchanged with the default\nvalue `true`.\n\nIn other scenarios, you may switch it to `false`.\n\n\n## Auto Push all Issue Collection Commits\n\nAutomatically pushes after each cs to the upstream repository. If you\ndidn't change the default locations, where your source code repository actually\nis the upstream repository of your issue collection, you will want to leave this\nunchanged with the default value of `true`.\n\nIn other scenarios, you may switch it to false. E.g. if the issue collection is\npart of your project wiki, then automatic pushing might lead to remote\noperations, which is not desirable.\n\n\n## Online commit summary prefix\n\nWith some GIT backends, it is possible to obtain a summary with changes and\ncommit message online for every commit. To use this facility, place a prefix\nin the config file, where the hash of a commit can be appended, to obtain a\nvalid link for that very commit.\n\nIf TrackDown discovers common GIT services, it tries to automatically discover\nthe correct prefix for URLs pointing to single commits.\n\n\n## Username for assignments\n\nTo be able to assign tickets to users, and thus to know who you are, the user\nname as used in the issue collection file can be added here. This makes it\npossible e.g. to list issues assigned to the current user.\n\nTickets won't be automatically be assigned when adding commits for an issue.\nJust the progress flag will be set.\n\n\n# Installation\n\nWhen building TrackDown locally, preliminary DEB and RPM packages will be\ncreated. But when downloading one of the releases or a snapshot, copy the files\nfrom bin/ to a place on your $PATH for now. For some functions - especially in\nthe area of issue tracker mirror - [jq][jq] needs to be installed.\n\nOf course, this way the remaining Windows users are locked out.\n\nA symbolic link `td` to the `trackdown.sh` script is recommended for easier\nuse.\n\n\n## Compatibility\n\nTrackDown is tested to work with Debian 11 and newer. It is expected to work\non similar Linux systems and MacOS systems. Also [NetBeans][netbeans] internal\nGIT implementation should work.\n\nThere are no plans to support Windows systems directly.\n\n\n## Prerequisites\n\nTrackDown relies on a [GIT][git] or [Mercurial][hg] installation available on\nthe path when used with distributed version control as the backend. The\nmirror feature in turn heavily relies on the installation of [jq][jq] available\nthrough your path.\n\n\n# Related Projects\n\nI only came across related projects which have certain limitations or are\nunmaintained. In each case, the limitations have an extent that kept me from\nusing these systems except for very small or test projects.\n\n\n## Fossil SCM\n\nWhat I liked about fossil is, that it brings the three core elements of development\n\n- Source Code\n- Documentation or Notes (Wiki)\n- Issues\n\nlocal to my machine for distributed development or disconnected situations.\n\nYou don't have to maintain backups since the remote instances are your backups\nof the source code, wiki, and ticketing state.\n\nIt does not have a wiki capable of shared editing with later merging, like the\n[GIT][git] based wikis of [GitLab][gitlab], [GitHub][github],\n[Forgejo][forgejo], or [Bitbucket][bitbucket].\n\nAlso, it is not possible to the contents of the wiki outside the\n[Fossil][fossil] context e.g. for a documentation website, since you cannot\nexport the wikis raw data. (Yes, [Fossil][fossil] provides means to use the\nwiki directly as a documentation site system, which is similar but not exactly\nthe same.)\n\nThe drawback is, that it does all these things by creating a nearly closed shop\nsystem not open to re-use of these elements and not open to external tooling\noutside the [Fossil][fossil] scripting facility.\n\nAdditionally, I have to keep the [Fossil][fossil] internal web server running\nfor each repository I am using, to be able to read the notes and issues for a\nproject.\n\nAlso, there is only poor IDE support for [Fossil][fossil] right now, with the\nexception of support for [Idea](https://plugins.jetbrains.com/plugin/7479)\nand my own small [plug-in for NetBeans](http://chiselapp.com/user/backendzeit/repository/netbeans-fossil-plugin/index)\nmirrored [here](https://github.com/mgoellnitz/netbeans-fossil-plugin).\n\n\n## Forgejo (Gitea and Gogs)\n\nOriginally coming from the root of [Gitea][gitea] and [Gogs][gogs],\n[Forgejo][forgejo] has been forked and extended. Intended for on premises use\nas a [GIT][git] based solution for Code, Wiki and CI together with an issue\ntracking section, it is also available in the form of the public online\nincarnation [Codeberg](codeberg).\n\nOf course [Forgejo][forgejo] can be used as a TrackDown storage backend or\nmirroring source.\n\nWe also expect the related [Gitea][gitea] and [Gogs][gogs] system to be still\nfully usable in the same way.\n\n\n## GitHub\n\n[GitHub][github] is the obvious solution used in so many [GIT][git] powered\nprojects together with a [GIT][git] based wiki (as opposed to\n[Bitbucket][bitbucket] and  [GitLab][gitlab] the Wiki is a flat folder - be\nwarned) and many other useful details.\n\nThe only thing I'm missing is the distributed offline work for ticketing.\n\nSo in this case it is possible to leave out the ticketing of [GitHub][github]\nand use TrackDown with [GitHub][github] as the [GIT][git] based\nstorage backend. And this is exactly what TrackDown was designed for.\n\nAs an alternative, you can at least mirror the issues from [GitHub][github] to\nhave your notes with you and at least know the issue IDs for offline code\ncommits. Or you can use the mirroring steps for migration purposes.\n\n\n## GitLab\n\n[GitLab][gitlab] not only is a good online solution but also is a piece of\non premises software (like Bitbucket for the renamed git-Part - not hg.). It's\nwiki is also [GIT][git] based wiki, and it comes with a wealth of other\nintegrations and useful tools and details.\n\nThe only thing I'm missing is the distributed offline work for ticketing.\n\nSo in this case it is possible to leave out the ticketing of [GitLab][gitlab]\nand use TrackDown with [GitLab][gitlab] as the [GIT][git] based\nstorage backend. And this is exactly what TrackDown was designed for.\n\nAs an alternative, you can at least mirror the issues from [GitLab][gitlab] to\nhave the notes with you and now the issue IDs for offline code commits.\n\n\n## Bitbucket\n\n[Bitbucket.org][bitbucket] is a decent tool for open source or small projects.\nIt has decent VCS solutions, a wiki which can be used distributed through\n[GIT][git]. In the past they were a brilliant backend for TrackDown with both\nVCS  solutions, since they also provided support for [Mercurial][hg], which was\nabandoned in mid 2020.\n\nThe only thing I'm missing is the distributed offline work for ticketing.\n\nSo in this case it is possible to leave out the ticketing of [Bitbucket][bitbucket]\nand use TrackDown with [Bitbucket][bitbucket] as the [GIT][git] based storage\nbackend. And this is exactly what TrackDown was designed for. For migration\npurposes, or if the limited issue tracking within bitbucket.org is sufficient, the\nmirroring feature might come in handy.\n\nAtlassian themselves recommends using Jira.\n\n\n## Trac\n\nA few years ago, a colleague stated that he is running a local VM for each\nproject, he is involved with, to take notes, track issues, and maintain source\ncode.\n\nOf course, this does not imply shared use of the Trac service or disconnected use.\n\nAlso, while Trac is a brilliant tool, this leaves me with the necessity to\nmaintain the locally running instances and take backups of them, in addition to\nthe project VCS and source code repositories. This is not the case for the\n[GIT][git] based solutions in this list, which have a remote repository as a\nbackup wiki and source code.\n\n\n## Other VCS Services\n\nA small list of tested backends for TrackDown which don't support any kind of\nissue tracking but Code and Wiki with the VCS:\n\n* [Helix Team Hub][hth]\n* [Visual Studio Services][vss]\n\n\n## MDWiki\n\nUnlike [Blogdown](https://github.com/gernest/blogdown) where you again start\na server - but this time on localhost, [MDWiki][mdwiki] just runs in your\nbrowser to view Markdown files nicely formatted locally.\n\n```\nfile:///home/me/somewhere/thats/green/repo/wiki.html#!issues.md\nfile:///home/me/somewhere/thats/green/repo/wiki.html#!roadmap.md\n```\n\nThe output of TrackDown looks pretty usable in this setup and gives a good\noverview of the issues as the roadmap.\n\nWhen you also use GitLab, GitHub, or Bitbucket Wikis, [MDWiki][mdwiki] has\na different understanding, how links should be interpreted. To get a fully\ncompatible local and remote viewing setup for these cases, a patched\nversion of [MDWiki][mdwiki] [exists on GitHub](https://github.com/mgoellnitz/mdwiki/).\n\n\n## Unmaintained related Projects\n\nThese seem to address similar issues, but are not under active development\n\n - [GitIssius][gitissius]\n - [Distributed Issue Tracker](https://github.com/keredson/distributed-issue-tracker)\n - [Bugs Everywhere][be]\n\n\n# Migration and Offline Mirroring\n\nTo facilitate the use of TrackDown, the option of migrating an existing base\nof tickets is helpful, of course. The choice, which systems are taken as a\ndata source for such a migration is driven by personal needs.\n\n\n## GitHub Offline Mirror\n\nFor disconnected situations which TrackDown is supposed to support, it is\npossible to connect a workspace to its [GitHub][github] issue tracker and\nmirror tickets for offline use.\n\nThe mirror - of course - is not intended for changing the issues in the issue\ncollection file. State changes will most likely be triggered on [GitHub][github]\nby your commit messages or manually, after which a call of the mirroring script\ncan be helpful.\n\nInstead of `trackdown.sh use` issue `trackdown.sh github` to set up the mirror\nconnection.\n\n```\ntrackdown.sh github \u003cprojectname\u003e \u003cowner\u003e \u003capitoken\u003e\n```\n\nAfterwards, anytime you can connect to the [GitHub][github] system, collect the\ncurrent mirror state to your local issue collection file and the roadmap.\n\n```\ntrackdown.sh mirror\n```\n\nAdditionally - since you now are on your command line and perhaps don't want\nto switch windows every second - there is a `remote` command to issue commands\non the remote mirroring source system.\n\nYou have to provide the issue-id and the id of the user, which is also always\nexported to the issue collection file to facilitate this.\n\nThe commands available are\n\n* `assign` to assign issues to users\n\n```\ntrackdown.sh remote assign 68 XYZ\nAssigning 68 to user XYZ\n```\n\n* `comment` to comment issues\n\n```\ntrackdown.sh remote comment 68 \"Just a comment\"\nAdding comment \"Just a comment\" to issue 68\n```\n\n\n## GitLab Offline Mirror\n\nFor disconnected situations which TrackDown is supposed to support, it is\npossible to connect a workspace to its [GitLab][gitlab] issue tracker and\nmirror tickets for offline use.\n\nThe mirror - of course - is not intended for changing the issues in the issue\ncollection file. State changes will most likely be triggered on [GitLab][gitlab]\nby your commit messages or manually, after which a call of the mirroring script\ncan be helpful.\n\nInstead of `trackdown.sh use` issue `trackdown.sh gitlab` to set up the mirror\nconnection.\n\n```\ntrackdown.sh gitlab \u003capitoken\u003e \u003cprojectname\u003e [https://\u003cgitlab.host\u003e]\n```\n\nIf you omit the URL prefix, `https://gitlab.com` is used. The project name must\nbe given without any group or user addition.\n\nAfterwards, anytime you can connect to the [GitLab][gitlab] system, collect the\ncurrent mirror state to your local issue collection file and the roadmap.\n\n```\ntrackdown.sh mirror\n```\n\nAdditionally, since you now are on your command line and perhaps don't want\nto switch windows every second, there is a `remote` command to issue commands\non the remote mirroring source system.\n\n```\ntrackdown.sh remote assign 68 XYZ\nAssigning 68 to user XYZ\n```\n\nYou have to provide the issue-id and the id of the user, which is also always\nexported to the issue collection file to facilitate this.\n\nThe commands available are\n\n* `assign` to assign issues to users\n\n```\ntrackdown.sh remote assign 68 XYZ\nAssigning 68 to user XYZ\n```\n\n* `comment` to comment issues\n\n```\ntrackdown.sh remote comment 68 \"Just a comment\"\nAdding comment \"Just a comment\" to issue 68\n```\n\n* `assign` to assign issues to users\n\n* `milestone` to put issues into milestones\n\n\n## Gitea Offline Mirror\n\nFor disconnected situations which TrackDown is supposed to support, it is\npossible to connect a workspace to its [Gitea][gitea] issue tracker and mirror\ntickets for offline use.\n\nSetup parameters default to values from the [Git][git] repository your current\nlocal directory points to.\n\nThe mirror - of course - is not intended for changing the issues in the issue\ncollection file. State changes will most likely be triggered on the [Gitea][gitea]\ninstance in use by your commit messages or manually, after which a call of the\nmirroring script can be helpful.\n\nInstead of `trackdown.sh use` issue `trackdown.sh gitea` to set up the mirror\nconnection.\n\n```\ntrackdown.sh gitea \u003capitoken\u003e \u003cprojectname\u003e [https://\u003cgitea.host\u003e]\n```\n\nIf you omit the URL prefix and no values can be derived from your current\nworking directory, `https://codeberg.org` is used.\n\nAfterwards, anytime you can connect to the [Gitea][gitea] system, collect the\ncurrent mirror state to your local issue collection file and the roadmap.\n\n```\ntrackdown.sh mirror\n```\n\nAdditionally - since you now are on your command line and perhaps don't want\nto switch windows every second - there is a `remote` command to issue commands\non the remote mirroring source system.\n\nYou have to provide the issue id and the id of the user, which is also always\nexported to the issue collection file to facilitate this.\n\nThe commands available are\n\n* `assign` to assign issues to users\n\n```\ntrackdown.sh remote assign 68 XYZ\nAssigning 68 to user XYZ\n```\n\n* `comment` to comment issues\n\n```\ntrackdown.sh remote comment 68 \"Just a comment\"\nAdding comment \"Just a comment\" to issue 68\n```\n\nIt is expected that this also works for [Gogs](gogs) backends as well.\n\n\n## Bitbucket.org Offline Mirror\n\nFor disconnected situations which TrackDown is supposed to support, it is\npossible to connect a workspace to its [Bitbucket.org][bitbucket] issue\ntracker and mirror tickets for offline use.\n\nSome of my stalled projects reside there, and I already did an export of the\nissue tracker contents, which is what [Bitbucket.org][bitbucket] supports.\n\nOffline mirror capabilities are now added to this tool for smother migration\naway from the proprietary issue tracker.\n\nThe mirror again is not intended for changing the issues in the issue\ncollection file. State changes will most likely be triggered on\n[Bitbucket.org][bitbucket] by your commit messages or manually, after which a\ncall of the mirroring script can be helpful.\n\nInstead of `trackdown.sh use` issue `trackdown.sh github` to set up the mirror\nconnection.\n\n```\ntrackdown.sh bitbucket \u003cprojectname\u003e \u003cowner\u003e \u003capp-password\u003e\n```\n\nAfterwards, anytime you can connect to the [Bitbucket.org][bitbucket] system,\ncollect the current mirror state to your local issue collection file and the\nroadmap.\n\n```\ntrackdown.sh mirror\n```\n\nIn the case of [Bitbucket.org][bitbucket], the mirror script has to ask for\nyou password on [Bitbucket.org][bitbucket], if you leave out the app password.\nApp passwords can be generated in the personal [Bitbucket.org][bitbucket]\nsettings.\n\nAdditionally - since you now are on your command line and perhaps don't want\nto switch windows every second - there is a `remote` command to issue commands\non the remote mirroring source system.\n\nThe commands available are\n\n* `assign` to assign issues to users\n\n```\ntrackdown.sh remote assign 68 XYZ\nAssigning 68 to user XYZ\n```\n\n* `comment` to comment issues\n\n```\ntrackdown.sh remote comment 68 \"Just a comment\"\nAdding comment \"Just a comment\" to issue 68\n```\n\n\n## Redmine\n\nFor historical reasons, my [Tangram](https://github.com/mgoellnitz/tangram)\nproject used [Redmine][redmine] some time ago and customers also used\n[Redmine][redmine]. So there are two scenarios where some interfacing would be\nhelpful.\n\nIn addition, the roadmap outline of TrackDown is very much inspired by the\n[Redmine][redmine] roadmap page.\n\n### Offline mirror\n\nSince I'm - sad enough - not in the position to tell my enterprise scale\ncustomers which ticketing systems to use, there is still the need to have\nthe issue descriptions, ticket ID, target versions, affected versions and\neven the roadmap available offline.\n\nFor an offline mirror without the capability to change the status of tickets,\nthe following setup workflow is used instead of the steps given above:\n\nInstead of `trackdown.sh use` issue `trackdown.sh redmine` to set up the mirror\nconnection.\n\n```\ntrackdown.sh redmine \u003capikey\u003e \u003cprojectname\u003e[,\u003cprojectname\u003e...] https://\u003credmine.host\u003e/\n```\n\nAfterwards, anytime you can connect to the [Redmine][redmine] system, collect the\ncurrent mirror state to your local issue collection file and the roadmap.\n\n```\ntrackdown.sh mirror\n```\n\nAdditionally, since you now are on your command line and perhaps don't want\nto switch windows every second, there is a `remote` command to issue commands\non the remote mirroring source system.\n\n```\ntrackdown.sh remote comment XYZ \"Hi there.\"\nAdding comment \"Hi there.\" to XYZ\n```\n\n```\ntrackdown.sh remote assign 68 XYZ\nAssigning 68 to user XYZ\n```\n\nYou have to provide the id of the user - not its name, which is also always\nexported to the issue collection file to facility this.\n\n\n### Migration\n\nWhen you think the information mirrored right now is sufficient to cut the ties,\nyou can set up the created issue collection and roadmap as the repository and do\na `trackdown.sh use`.\n\nThe full migration is not covered by a command yet, and setting up the mirrored\ndata in the special TrackDown branch or any other location of your choosing must\nbe accomplished manually. The needed steps include:\n\n*Latest Mirror*\n\nGet the latest mirrored data.\n\n```\ntrackdown.sh mirror\n```\n\n*Remove Mirror Configuration*\n\n```\nrm -rf .trackdown\n```\n\n*Initialize TrackDown*\n\nSpecial Branch Flavour:\n\n```\ntrackdown.sh init\ntrackdown.sh use\nmv old-issues.md .git/trackdown/issues.md # or .hg\nroadmap.md .git/trackdown/roadmap.md # or .hg\n```\n\nCustom location - e.g. wiki\n\n```\nmv old-issues.md ../wiki/issues.md\nroadmap.md ../wiki/roadmap.md\ntrackdown.sh use ../wiki/issues.md\n(cd wiki; git add issues.md roadmap.md)  # or hg\n```\n\n*Clean Up*\n\nSince the mirroring collects as much data as possible, it might be a good idea\nto separate already closed releases or milestones from the currently relevant\nissues in the issue collection. Use the copy command to do so:\n\n```\ntrackdown.sh copy Milestone1\n```\n\nAnd now use the remaining issues as the new collection and add the separated\nissues as a changes/changelog part to your documentation.\n\n```\nmv ../wiki/Milestone1-issues.md ../wiki/issues.md\n(cd ../wiki ; git add Milestone1.md) # or hg\n```\n\nOf course, this cannot only be done for mirror issue collections and is e.g.\nused for TrackDown itself, like for release 1.0 in\n[this](https://github.com/mgoellnitz/trackdown/blob/trackdown/1.0.md) and\n[this](https://gitlab.com/mgoellnitz/trackdown/blob/trackdown/1.0.md) file.\n\n\n[markdown]: https://daringfireball.net/projects/markdown/\n[mdwiki]: http://mdwiki.info\n[jq]: https://stedolan.github.io/jq/\n[jgit]: https://eclipse.org/jgit/\n[trac]: http://trac.edgewall.org/\n[fossil]: http://fossil-scm.org/index.html/doc/trunk/www/index.wiki\n[redmine]: http://www.redmine.org/\n[be]: http://www.bugseverywhere.org/\n[gitissius]: https://github.com/glogiotatidis/gitissius\n[git]: http://git-scm.com/\n[hg]: https://www.mercurial-scm.org/\n[bitbucket]: https://bitbucket.org/\n[gitlab]: https://gitlab.com/\n[github]: https://github.com/\n[forgejo]: https://forgejo.org/\n[gogs]: https://gogs.io/\n[gitea]: https://gitea.io/\n[codeberg]: https://codeberg.org/\n[hth]: https://www.perforce.com/products/helix-teamhub\n[vss]: https://www.visualstudio.com/team-services/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgoellnitz%2Ftrackdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmgoellnitz%2Ftrackdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmgoellnitz%2Ftrackdown/lists"}