diff options
Diffstat (limited to 'doc')
45 files changed, 261 insertions, 257 deletions
diff --git a/doc/contrib/commit-message-guidelines.md b/doc/contrib/commit-message-guidelines.md new file mode 100644 index 000000000..e56b22e8a --- /dev/null +++ b/doc/contrib/commit-message-guidelines.md @@ -0,0 +1,198 @@ +# Commit message guidelines + +We have very strict rules over how commit messages must be formatted. This +format leads to easier to read commit history, and makes it possible to generate +a changelog for releases. + +<!-- mdformat-toc start --slug=github --maxlevel=4 --minlevel=2 --> + +- [Specification](#specification) + - [Format overview](#format-overview) + - [Type (required)](#type-required) + - [Scope (optional)](#scope-optional) + - [Subject (required)](#subject-required) + - [Body (optional)](#body-optional) + - [Anchors / Hyperlinks](#anchors--hyperlinks) + - [Footer (optional, conditionally required)](#footer-optional-conditionally-required) + - [Breaking changes](#breaking-changes) + +<!-- mdformat-toc end --> + +## Specification<a name="specification"></a> + +Commit subjects and messages should follow the format specified below, which is +a superset of the conventional commits specification +[version `1.0.0`][cc-1.0.0]. + +**A superset? What's different?** + +We require just one small change from the spec: + +- Appending the type and scope with `!` is _always_ required for breaking + changes. This is done by improve visibility of breaking changes in the commit + log. + +### Format overview<a name="format-overview"></a> + +``` +<type>[scope][!]: <subject> + +[optional body] + +[optional footer(s)] +``` + +### Type (required)<a name="type-required"></a> + +Valid values for `type` MUST be one of the following: + +| Type | Description | +| ---------- | ---------------------------------------------------- | +| `build` | Changes that affect the build system or dependencies | +| `ci` | Changes to the CI configuration files | +| `docs` | Changes consisting only of documentation changes | +| `feat` | A new feature | +| `fix` | A bug fix | +| `perf` | Changes that improve performance | +| `refactor` | A change that neither fixes a bug or adds a feature | +| `test` | Adding missing tests or correcting existing tests | + +### Scope (optional)<a name="scope-optional"></a> + +The scope should be the app or package name as it would be perceived by a person +reading the changelog. + +The following scopes are supported: + +- `api` +- `bridge` +- `bridge/github` +- `bridge/gitlab` +- `bridge/jira` +- `bugs` +- `cache` +- `cli` +- `config` +- `git` +- `tui` +- `web` + +There are a few exceptions to the "use the package name" rule: + +- `changelog`: used for changes related to the changelog or its generation +- `dev-infra`: used for developer-centric changes (docs, scripts, tools, etc) +- `treewide`: used for repo-wide changes (e.g. bulk formatting, refactoring) +- _none / unset_: useful for `build`, `ci`, and `test` (if changing a test lib, + or multiple tests) + +### Subject (required)<a name="subject-required"></a> + +The subject should contain a succinct, descriptive summary of the change. + +- Use the imperative, present tense: "change" not "changed" or "changes" +- Do not use capital letters, except in acronyms (like `HTTP`) +- Do not end the subject with a `.` or `?` or any similar end-of-sentence symbol + +### Body (optional)<a name="body-optional"></a> + +The body is used to provide additional context: the _what_, _why_, and _how_ for +the change. Just as in the **subject**, use the imperative tense. The body +should contain the motivation for the change, and contrast it with the previous +behavior. + +#### Anchors / Hyperlinks<a name="anchors--hyperlinks"></a> + +If you include anchors, otherwise known as hyperlinks (or just "links") in the +body, be sure to use the _reference style_ for anchor links. + +**Incorrect - do not use inline links** + +``` +Lorem ipsum dolar [sit amet](https://foo.com), consectetur adipiscing elit. In +hendrerit orci et risus vehicula venenatis. +``` + +**Correct - use reference style links** + +Both of the below examples are valid. + +``` +Lorem ipsum dolar [sit amet][0], consectetur adipiscing elit. In hendrerit orci +et risus vehicula venenatis. + +[0]: https://foo.com +``` + +``` +Lorem ipsum dolar sit amet [0], consectetur adipiscing elit. In hendrerit orci +et risus vehicula venenatis. + +[0]: https://foo.com +``` + +### Footer (optional, conditionally required)<a name="footer-optional-conditionally-required"></a> + +The footer should contain any information about **breaking changes** (see below) +and is also the place to reference issues that the change closes, if any. + +**Examples** + +``` +Closes: #000 +Closes: git-bug/git-bug#000 +Fixes: #000 +Ref: https://domain.com/some-page/foo/bar +Ref: https://github.com/git-bug/git-bug/discussions/000 +``` + +#### Breaking changes<a name="breaking-changes"></a> + +To indicate that a commit introduces a breaking change, append `!` after the +type and scope (**this is required**). You can optionally provide additional +information (for example, migration instructions) by adding a `BREAKING-CHANGE` +trailer to the footer. This additional information will be shown in the +changelog. + +> [!NOTE] +> Breaking changes in this repository **always require** the `!` suffix in order +> to improve visibility of breaking changes in the commit log. + +**Examples** + +Below are commit message examples you can use as references for writing a commit +message for a breaking change. + +**Unscoped breaking change without additional information** + +``` +feat!: remove the ABC bridge +``` + +**Scoped breaking change without additional information** + +``` +feat(config)!: remove configuration option: foo.bar +``` + +**Scoped breaking change with additional information** + +``` +feat(config)!: remove option: foo.bar + +BREAKING-CHANGE: Users should migrate to `bar.baz` +``` + +**Scoped breaking change with multiple lines** + +If your breaking change description spans multiple lines, be sure to indent each +subsequent line with at least one space so that the message is parsed correctly. + +``` +feat(config)!: remove option: foo.bar + +BREAKING-CHANGE: Users should migrate to `bar.baz` in order to continue + operating the tool and avoid a parsing error when the configuration is loaded, + which would throw an error stating that the `foo.bar` option doesn't exist. +``` + +[cc-1.0.0]: https://www.conventionalcommits.org/en/v1.0.0/#specification diff --git a/doc/generate.go b/doc/generate.go index 0001f1a77..005d9df76 100644 --- a/doc/generate.go +++ b/doc/generate.go @@ -34,7 +34,7 @@ func main() { wg.Add(1) go func(name string, f func(*cobra.Command) error) { defer wg.Done() - root := commands.NewRootCommand() + root := commands.NewRootCommand("") err := f(root) if err != nil { fmt.Printf(" - %s: FATAL\n", name) diff --git a/doc/man/git-bug-bridge-auth-add-token.1 b/doc/man/git-bug-bridge-auth-add-token.1 index dda8839fd..9314e5e00 100644 --- a/doc/man/git-bug-bridge-auth-add-token.1 +++ b/doc/man/git-bug-bridge-auth-add-token.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bridge-auth-add-token - Store a new token .SH SYNOPSIS -.PP \fBgit-bug bridge auth add-token [TOKEN] [flags]\fP .SH DESCRIPTION -.PP Store a new token .SH OPTIONS -.PP \fB-t\fP, \fB--target\fP="" The target of the bridge. Valid values are [github,gitlab,jira,launchpad-preview] @@ -35,5 +31,4 @@ Store a new token .SH SEE ALSO -.PP \fBgit-bug-bridge-auth(1)\fP diff --git a/doc/man/git-bug-bridge-auth-rm.1 b/doc/man/git-bug-bridge-auth-rm.1 index 4ce7672c5..ff0034fe2 100644 --- a/doc/man/git-bug-bridge-auth-rm.1 +++ b/doc/man/git-bug-bridge-auth-rm.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bridge-auth-rm - Remove a credential .SH SYNOPSIS -.PP \fBgit-bug bridge auth rm BRIDGE_ID [flags]\fP .SH DESCRIPTION -.PP Remove a credential .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for rm .SH SEE ALSO -.PP \fBgit-bug-bridge-auth(1)\fP diff --git a/doc/man/git-bug-bridge-auth-show.1 b/doc/man/git-bug-bridge-auth-show.1 index 1c4385ffc..900943132 100644 --- a/doc/man/git-bug-bridge-auth-show.1 +++ b/doc/man/git-bug-bridge-auth-show.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bridge-auth-show - Display an authentication credential .SH SYNOPSIS -.PP \fBgit-bug bridge auth show [flags]\fP .SH DESCRIPTION -.PP Display an authentication credential .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for show .SH SEE ALSO -.PP \fBgit-bug-bridge-auth(1)\fP diff --git a/doc/man/git-bug-bridge-auth.1 b/doc/man/git-bug-bridge-auth.1 index f6f36623f..3d168bbf2 100644 --- a/doc/man/git-bug-bridge-auth.1 +++ b/doc/man/git-bug-bridge-auth.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bridge-auth - List all known bridge authentication credentials .SH SYNOPSIS -.PP \fBgit-bug bridge auth [flags]\fP .SH DESCRIPTION -.PP List all known bridge authentication credentials .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for auth .SH SEE ALSO -.PP \fBgit-bug-bridge(1)\fP, \fBgit-bug-bridge-auth-add-token(1)\fP, \fBgit-bug-bridge-auth-rm(1)\fP, \fBgit-bug-bridge-auth-show(1)\fP diff --git a/doc/man/git-bug-bridge-new.1 b/doc/man/git-bug-bridge-new.1 index 5911843e4..f9b11853d 100644 --- a/doc/man/git-bug-bridge-new.1 +++ b/doc/man/git-bug-bridge-new.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bridge-new - Configure a new bridge .SH SYNOPSIS -.PP \fBgit-bug bridge new [flags]\fP .SH DESCRIPTION -.PP Configure a new bridge by passing flags or/and using interactive terminal prompts. You can avoid all the terminal prompts by passing all the necessary flags to configure your bridge. .SH OPTIONS -.PP \fB-n\fP, \fB--name\fP="" A distinctive name to identify the bridge @@ -124,5 +120,4 @@ git bug bridge new \\ .SH SEE ALSO -.PP \fBgit-bug-bridge(1)\fP diff --git a/doc/man/git-bug-bridge-pull.1 b/doc/man/git-bug-bridge-pull.1 index 4d39b0d78..e73383574 100644 --- a/doc/man/git-bug-bridge-pull.1 +++ b/doc/man/git-bug-bridge-pull.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bridge-pull - Pull updates from a remote bug tracker .SH SYNOPSIS -.PP \fBgit-bug bridge pull [NAME] [flags]\fP .SH DESCRIPTION -.PP Pull updates from a remote bug tracker .SH OPTIONS -.PP \fB-n\fP, \fB--no-resume\fP[=false] force importing all bugs @@ -31,5 +27,4 @@ Pull updates from a remote bug tracker .SH SEE ALSO -.PP \fBgit-bug-bridge(1)\fP diff --git a/doc/man/git-bug-bridge-push.1 b/doc/man/git-bug-bridge-push.1 index 9541c527f..b67055231 100644 --- a/doc/man/git-bug-bridge-push.1 +++ b/doc/man/git-bug-bridge-push.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bridge-push - Push updates to remote bug tracker .SH SYNOPSIS -.PP \fBgit-bug bridge push [NAME] [flags]\fP .SH DESCRIPTION -.PP Push updates to remote bug tracker .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for push .SH SEE ALSO -.PP \fBgit-bug-bridge(1)\fP diff --git a/doc/man/git-bug-bridge-rm.1 b/doc/man/git-bug-bridge-rm.1 index 6010eca8e..c2ced2126 100644 --- a/doc/man/git-bug-bridge-rm.1 +++ b/doc/man/git-bug-bridge-rm.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bridge-rm - Delete a configured bridge .SH SYNOPSIS -.PP \fBgit-bug bridge rm NAME [flags]\fP .SH DESCRIPTION -.PP Delete a configured bridge .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for rm .SH SEE ALSO -.PP \fBgit-bug-bridge(1)\fP diff --git a/doc/man/git-bug-bridge.1 b/doc/man/git-bug-bridge.1 index 7fbce2c19..48f43a99a 100644 --- a/doc/man/git-bug-bridge.1 +++ b/doc/man/git-bug-bridge.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bridge - List bridges to other bug trackers .SH SYNOPSIS -.PP \fBgit-bug bridge [flags]\fP .SH DESCRIPTION -.PP List bridges to other bug trackers .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for bridge .SH SEE ALSO -.PP \fBgit-bug(1)\fP, \fBgit-bug-bridge-auth(1)\fP, \fBgit-bug-bridge-new(1)\fP, \fBgit-bug-bridge-pull(1)\fP, \fBgit-bug-bridge-push(1)\fP, \fBgit-bug-bridge-rm(1)\fP diff --git a/doc/man/git-bug-bug-comment-edit.1 b/doc/man/git-bug-bug-comment-edit.1 index 5a3d3506a..e6146332b 100644 --- a/doc/man/git-bug-bug-comment-edit.1 +++ b/doc/man/git-bug-bug-comment-edit.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-comment-edit - Edit an existing comment on a bug .SH SYNOPSIS -.PP \fBgit-bug bug comment edit [COMMENT_ID] [flags]\fP .SH DESCRIPTION -.PP Edit an existing comment on a bug .SH OPTIONS -.PP \fB-F\fP, \fB--file\fP="" Take the message from the given file. Use - to read the message from the standard input @@ -35,5 +31,4 @@ Edit an existing comment on a bug .SH SEE ALSO -.PP \fBgit-bug-bug-comment(1)\fP diff --git a/doc/man/git-bug-bug-comment-new.1 b/doc/man/git-bug-bug-comment-new.1 index f2afc9338..a68e3fc82 100644 --- a/doc/man/git-bug-bug-comment-new.1 +++ b/doc/man/git-bug-bug-comment-new.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-comment-new - Add a new comment to a bug .SH SYNOPSIS -.PP \fBgit-bug bug comment new [BUG_ID] [flags]\fP .SH DESCRIPTION -.PP Add a new comment to a bug .SH OPTIONS -.PP \fB-F\fP, \fB--file\fP="" Take the message from the given file. Use - to read the message from the standard input @@ -35,5 +31,4 @@ Add a new comment to a bug .SH SEE ALSO -.PP \fBgit-bug-bug-comment(1)\fP diff --git a/doc/man/git-bug-bug-comment.1 b/doc/man/git-bug-bug-comment.1 index 162c41826..80a95134d 100644 --- a/doc/man/git-bug-bug-comment.1 +++ b/doc/man/git-bug-bug-comment.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-comment - List a bug's comments .SH SYNOPSIS -.PP \fBgit-bug bug comment [BUG_ID] [flags]\fP .SH DESCRIPTION -.PP List a bug's comments .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for comment .SH SEE ALSO -.PP \fBgit-bug-bug(1)\fP, \fBgit-bug-bug-comment-edit(1)\fP, \fBgit-bug-bug-comment-new(1)\fP diff --git a/doc/man/git-bug-bug-deselect.1 b/doc/man/git-bug-bug-deselect.1 index a648735e0..a111d8c9b 100644 --- a/doc/man/git-bug-bug-deselect.1 +++ b/doc/man/git-bug-bug-deselect.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-deselect - Clear the implicitly selected bug .SH SYNOPSIS -.PP \fBgit-bug bug deselect [flags]\fP .SH DESCRIPTION -.PP Clear the implicitly selected bug .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for deselect @@ -33,5 +29,4 @@ git bug deselect .SH SEE ALSO -.PP \fBgit-bug-bug(1)\fP diff --git a/doc/man/git-bug-bug-label-new.1 b/doc/man/git-bug-bug-label-new.1 index aa2b0c652..4fc48cb65 100644 --- a/doc/man/git-bug-bug-label-new.1 +++ b/doc/man/git-bug-bug-label-new.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-label-new - Add a label to a bug .SH SYNOPSIS -.PP \fBgit-bug bug label new [BUG_ID] LABEL... [flags]\fP .SH DESCRIPTION -.PP Add a label to a bug .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for new .SH SEE ALSO -.PP \fBgit-bug-bug-label(1)\fP diff --git a/doc/man/git-bug-bug-label-rm.1 b/doc/man/git-bug-bug-label-rm.1 index b204d61f3..0fa52d8b7 100644 --- a/doc/man/git-bug-bug-label-rm.1 +++ b/doc/man/git-bug-bug-label-rm.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-label-rm - Remove a label from a bug .SH SYNOPSIS -.PP \fBgit-bug bug label rm [BUG_ID] LABEL... [flags]\fP .SH DESCRIPTION -.PP Remove a label from a bug .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for rm .SH SEE ALSO -.PP \fBgit-bug-bug-label(1)\fP diff --git a/doc/man/git-bug-bug-label.1 b/doc/man/git-bug-bug-label.1 index a98c22855..bc15d2341 100644 --- a/doc/man/git-bug-bug-label.1 +++ b/doc/man/git-bug-bug-label.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-label - Display labels of a bug .SH SYNOPSIS -.PP \fBgit-bug bug label [BUG_ID] [flags]\fP .SH DESCRIPTION -.PP Display labels of a bug .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for label .SH SEE ALSO -.PP \fBgit-bug-bug(1)\fP, \fBgit-bug-bug-label-new(1)\fP, \fBgit-bug-bug-label-rm(1)\fP diff --git a/doc/man/git-bug-bug-new.1 b/doc/man/git-bug-bug-new.1 index 91de2dcce..3639c1741 100644 --- a/doc/man/git-bug-bug-new.1 +++ b/doc/man/git-bug-bug-new.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-new - Create a new bug .SH SYNOPSIS -.PP \fBgit-bug bug new [flags]\fP .SH DESCRIPTION -.PP Create a new bug .SH OPTIONS -.PP \fB-t\fP, \fB--title\fP="" Provide a title to describe the issue @@ -39,5 +35,4 @@ Create a new bug .SH SEE ALSO -.PP \fBgit-bug-bug(1)\fP diff --git a/doc/man/git-bug-bug-rm.1 b/doc/man/git-bug-bug-rm.1 index ee7ea1851..6555ae684 100644 --- a/doc/man/git-bug-bug-rm.1 +++ b/doc/man/git-bug-bug-rm.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-rm - Remove an existing bug .SH SYNOPSIS -.PP \fBgit-bug bug rm BUG_ID [flags]\fP .SH DESCRIPTION -.PP Remove an existing bug in the local repository. Note removing bugs that were imported from bridges will not remove the bug on the remote, and will only remove the local copy of the bug. .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for rm .SH SEE ALSO -.PP \fBgit-bug-bug(1)\fP diff --git a/doc/man/git-bug-bug-select.1 b/doc/man/git-bug-bug-select.1 index 397cb9e84..06073e8b7 100644 --- a/doc/man/git-bug-bug-select.1 +++ b/doc/man/git-bug-bug-select.1 @@ -2,17 +2,14 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-select - Select a bug for implicit use in future commands .SH SYNOPSIS -.PP \fBgit-bug bug select BUG_ID [flags]\fP .SH DESCRIPTION -.PP Select a bug for implicit use in future commands. .PP @@ -26,7 +23,6 @@ The complementary command is "git bug deselect" performing the opposite operatio .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for select @@ -41,5 +37,4 @@ git bug status .SH SEE ALSO -.PP \fBgit-bug-bug(1)\fP diff --git a/doc/man/git-bug-bug-show.1 b/doc/man/git-bug-bug-show.1 index aec83fa33..295f0efb5 100644 --- a/doc/man/git-bug-bug-show.1 +++ b/doc/man/git-bug-bug-show.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-show - Display the details of a bug .SH SYNOPSIS -.PP \fBgit-bug bug show [BUG_ID] [flags]\fP .SH DESCRIPTION -.PP Display the details of a bug .SH OPTIONS -.PP \fB--field\fP="" Select field to display. Valid values are [author,authorEmail,createTime,lastEdit,humanId,id,labels,shortId,status,title,actors,participants] @@ -31,5 +27,4 @@ Display the details of a bug .SH SEE ALSO -.PP \fBgit-bug-bug(1)\fP diff --git a/doc/man/git-bug-bug-status-close.1 b/doc/man/git-bug-bug-status-close.1 index edd9f6666..4f89f8a19 100644 --- a/doc/man/git-bug-bug-status-close.1 +++ b/doc/man/git-bug-bug-status-close.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-status-close - Mark a bug as closed .SH SYNOPSIS -.PP \fBgit-bug bug status close [BUG_ID] [flags]\fP .SH DESCRIPTION -.PP Mark a bug as closed .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for close .SH SEE ALSO -.PP \fBgit-bug-bug-status(1)\fP diff --git a/doc/man/git-bug-bug-status-open.1 b/doc/man/git-bug-bug-status-open.1 index 4c001adae..5e45f2e26 100644 --- a/doc/man/git-bug-bug-status-open.1 +++ b/doc/man/git-bug-bug-status-open.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-status-open - Mark a bug as open .SH SYNOPSIS -.PP \fBgit-bug bug status open [BUG_ID] [flags]\fP .SH DESCRIPTION -.PP Mark a bug as open .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for open .SH SEE ALSO -.PP \fBgit-bug-bug-status(1)\fP diff --git a/doc/man/git-bug-bug-status.1 b/doc/man/git-bug-bug-status.1 index 7abcd1a54..9aad6cc51 100644 --- a/doc/man/git-bug-bug-status.1 +++ b/doc/man/git-bug-bug-status.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-status - Display the status of a bug .SH SYNOPSIS -.PP \fBgit-bug bug status [BUG_ID] [flags]\fP .SH DESCRIPTION -.PP Display the status of a bug .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for status .SH SEE ALSO -.PP \fBgit-bug-bug(1)\fP, \fBgit-bug-bug-status-close(1)\fP, \fBgit-bug-bug-status-open(1)\fP diff --git a/doc/man/git-bug-bug-title-edit.1 b/doc/man/git-bug-bug-title-edit.1 index c5e33c7ae..156aa6860 100644 --- a/doc/man/git-bug-bug-title-edit.1 +++ b/doc/man/git-bug-bug-title-edit.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-title-edit - Edit a title of a bug .SH SYNOPSIS -.PP \fBgit-bug bug title edit [BUG_ID] [flags]\fP .SH DESCRIPTION -.PP Edit a title of a bug .SH OPTIONS -.PP \fB-t\fP, \fB--title\fP="" Provide a title to describe the issue @@ -31,5 +27,4 @@ Edit a title of a bug .SH SEE ALSO -.PP \fBgit-bug-bug-title(1)\fP diff --git a/doc/man/git-bug-bug-title.1 b/doc/man/git-bug-bug-title.1 index 945680356..01e3957d5 100644 --- a/doc/man/git-bug-bug-title.1 +++ b/doc/man/git-bug-bug-title.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug-title - Display the title of a bug .SH SYNOPSIS -.PP \fBgit-bug bug title [BUG_ID] [flags]\fP .SH DESCRIPTION -.PP Display the title of a bug .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for title .SH SEE ALSO -.PP \fBgit-bug-bug(1)\fP, \fBgit-bug-bug-title-edit(1)\fP diff --git a/doc/man/git-bug-bug.1 b/doc/man/git-bug-bug.1 index 413d3ea4b..972a442e8 100644 --- a/doc/man/git-bug-bug.1 +++ b/doc/man/git-bug-bug.1 @@ -2,17 +2,14 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-bug - List bugs .SH SYNOPSIS -.PP \fBgit-bug bug [QUERY] [flags]\fP .SH DESCRIPTION -.PP Display a summary of each bugs. .PP @@ -20,7 +17,6 @@ You can pass an additional query to filter and order the list. This query can be .SH OPTIONS -.PP \fB-s\fP, \fB--status\fP=[] Filter by status. Valid values are [open,closed] @@ -87,5 +83,4 @@ git bug status:open --by creation "foo bar" baz .SH SEE ALSO -.PP \fBgit-bug(1)\fP, \fBgit-bug-bug-comment(1)\fP, \fBgit-bug-bug-deselect(1)\fP, \fBgit-bug-bug-label(1)\fP, \fBgit-bug-bug-new(1)\fP, \fBgit-bug-bug-rm(1)\fP, \fBgit-bug-bug-select(1)\fP, \fBgit-bug-bug-show(1)\fP, \fBgit-bug-bug-status(1)\fP, \fBgit-bug-bug-title(1)\fP diff --git a/doc/man/git-bug-commands.1 b/doc/man/git-bug-commands.1 deleted file mode 100644 index 1d508cddb..000000000 --- a/doc/man/git-bug-commands.1 +++ /dev/null @@ -1,31 +0,0 @@ -.nh -.TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" - -.SH NAME -.PP -git-bug-commands - Display available commands. - - -.SH SYNOPSIS -.PP -\fBgit-bug commands [flags]\fP - - -.SH DESCRIPTION -.PP -Display available commands. - - -.SH OPTIONS -.PP -\fB-p\fP, \fB--pretty\fP[=false] - Output the command description as well as Markdown compatible comment - -.PP -\fB-h\fP, \fB--help\fP[=false] - help for commands - - -.SH SEE ALSO -.PP -\fBgit-bug(1)\fP diff --git a/doc/man/git-bug-label.1 b/doc/man/git-bug-label.1 index 9de7d2c04..715562163 100644 --- a/doc/man/git-bug-label.1 +++ b/doc/man/git-bug-label.1 @@ -2,17 +2,14 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-label - List valid labels .SH SYNOPSIS -.PP \fBgit-bug label [flags]\fP .SH DESCRIPTION -.PP List valid labels. .PP @@ -20,11 +17,9 @@ Note: in the future, a proper label policy could be implemented where valid labe .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for label .SH SEE ALSO -.PP \fBgit-bug(1)\fP diff --git a/doc/man/git-bug-pull.1 b/doc/man/git-bug-pull.1 index 62485429c..319b4147c 100644 --- a/doc/man/git-bug-pull.1 +++ b/doc/man/git-bug-pull.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-pull - Pull updates from a git remote .SH SYNOPSIS -.PP \fBgit-bug pull [REMOTE] [flags]\fP .SH DESCRIPTION -.PP Pull updates from a git remote .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for pull .SH SEE ALSO -.PP \fBgit-bug(1)\fP diff --git a/doc/man/git-bug-push.1 b/doc/man/git-bug-push.1 index 2f15aacb8..6069868ee 100644 --- a/doc/man/git-bug-push.1 +++ b/doc/man/git-bug-push.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-push - Push updates to a git remote .SH SYNOPSIS -.PP \fBgit-bug push [REMOTE] [flags]\fP .SH DESCRIPTION -.PP Push updates to a git remote .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for push .SH SEE ALSO -.PP \fBgit-bug(1)\fP diff --git a/doc/man/git-bug-termui.1 b/doc/man/git-bug-termui.1 index 7409c9637..689fcfe78 100644 --- a/doc/man/git-bug-termui.1 +++ b/doc/man/git-bug-termui.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-termui - Launch the terminal UI .SH SYNOPSIS -.PP \fBgit-bug termui [flags]\fP .SH DESCRIPTION -.PP Launch the terminal UI .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for termui .SH SEE ALSO -.PP \fBgit-bug(1)\fP diff --git a/doc/man/git-bug-user-adopt.1 b/doc/man/git-bug-user-adopt.1 index f7f2c8955..74e2baab6 100644 --- a/doc/man/git-bug-user-adopt.1 +++ b/doc/man/git-bug-user-adopt.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-user-adopt - Adopt an existing identity as your own .SH SYNOPSIS -.PP \fBgit-bug user adopt USER_ID [flags]\fP .SH DESCRIPTION -.PP Adopt an existing identity as your own .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for adopt .SH SEE ALSO -.PP \fBgit-bug-user(1)\fP diff --git a/doc/man/git-bug-user-new.1 b/doc/man/git-bug-user-new.1 index cdb6f91f5..bb251e05a 100644 --- a/doc/man/git-bug-user-new.1 +++ b/doc/man/git-bug-user-new.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-user-new - Create a new identity .SH SYNOPSIS -.PP \fBgit-bug user new [flags]\fP .SH DESCRIPTION -.PP Create a new identity .SH OPTIONS -.PP \fB-a\fP, \fB--avatar\fP="" Avatar URL @@ -39,5 +35,4 @@ Create a new identity .SH SEE ALSO -.PP \fBgit-bug-user(1)\fP diff --git a/doc/man/git-bug-user-user.1 b/doc/man/git-bug-user-user.1 index f4bf83d80..503016d5f 100644 --- a/doc/man/git-bug-user-user.1 +++ b/doc/man/git-bug-user-user.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-user-user - Display a user identity .SH SYNOPSIS -.PP \fBgit-bug user user show [USER_ID] [flags]\fP .SH DESCRIPTION -.PP Display a user identity .SH OPTIONS -.PP \fB-f\fP, \fB--field\fP="" Select field to display. Valid values are [email,humanId,id,lastModification,lastModificationLamports,login,metadata,name] @@ -27,5 +23,4 @@ Display a user identity .SH SEE ALSO -.PP \fBgit-bug-user(1)\fP diff --git a/doc/man/git-bug-user.1 b/doc/man/git-bug-user.1 index 276d0e43a..110829eb6 100644 --- a/doc/man/git-bug-user.1 +++ b/doc/man/git-bug-user.1 @@ -2,22 +2,18 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-user - List identities .SH SYNOPSIS -.PP \fBgit-bug user [flags]\fP .SH DESCRIPTION -.PP List identities .SH OPTIONS -.PP \fB-f\fP, \fB--format\fP="default" Select the output formatting style. Valid values are [default,json] @@ -27,5 +23,4 @@ List identities .SH SEE ALSO -.PP \fBgit-bug(1)\fP, \fBgit-bug-user-adopt(1)\fP, \fBgit-bug-user-new(1)\fP, \fBgit-bug-user-user(1)\fP diff --git a/doc/man/git-bug-version.1 b/doc/man/git-bug-version.1 index 6b6882216..988849e8a 100644 --- a/doc/man/git-bug-version.1 +++ b/doc/man/git-bug-version.1 @@ -2,38 +2,52 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP -git-bug-version - Show git-bug version information +git-bug-version - Print version information .SH SYNOPSIS -.PP \fBgit-bug version [flags]\fP .SH DESCRIPTION +Print version information. + .PP -Show git-bug version information +Format: + git-bug [commit[/dirty]] +.PP +Format Description: + may be one of: + - A semantic version string, prefixed with a "v", e.g. v1.2.3 + - "undefined" (if not provided, or built with an invalid version string) -.SH OPTIONS .PP -\fB-n\fP, \fB--number\fP[=false] - Only show the version number +[commit], if present, is the commit hash that was checked out during the + build. This may be suffixed with '/dirty' if there were local file + modifications. This is indicative of your build being patched, or modified in + some way from the commit. .PP -\fB-c\fP, \fB--commit\fP[=false] - Only show the commit hash + is the version of the go compiler used for the build. .PP -\fB-a\fP, \fB--all\fP[=false] - Show all version information + is the target platform (GOOS). .PP + is the target architecture (GOARCH). + + +.SH OPTIONS \fB-h\fP, \fB--help\fP[=false] help for version +.SH EXAMPLE +.EX +git bug version +.EE + + .SH SEE ALSO -.PP \fBgit-bug(1)\fP diff --git a/doc/man/git-bug-webui.1 b/doc/man/git-bug-webui.1 index f6cdcfde0..66298e5e0 100644 --- a/doc/man/git-bug-webui.1 +++ b/doc/man/git-bug-webui.1 @@ -2,17 +2,14 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-webui - Launch the web UI .SH SYNOPSIS -.PP \fBgit-bug webui [flags]\fP .SH DESCRIPTION -.PP Launch the web UI. .PP @@ -21,7 +18,6 @@ Available git config: .SH OPTIONS -.PP \fB--host\fP="127.0.0.1" Network address or hostname to listen to (default to 127.0.0.1) @@ -55,5 +51,4 @@ Available git config: .SH SEE ALSO -.PP \fBgit-bug(1)\fP diff --git a/doc/man/git-bug-wipe.1 b/doc/man/git-bug-wipe.1 index fc3178f63..cad86b0f7 100644 --- a/doc/man/git-bug-wipe.1 +++ b/doc/man/git-bug-wipe.1 @@ -2,26 +2,21 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug-wipe - Wipe git-bug from the git repository .SH SYNOPSIS -.PP \fBgit-bug wipe [flags]\fP .SH DESCRIPTION -.PP Wipe git-bug from the git repository .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for wipe .SH SEE ALSO -.PP \fBgit-bug(1)\fP diff --git a/doc/man/git-bug.1 b/doc/man/git-bug.1 index 9bf59164f..7320689b4 100644 --- a/doc/man/git-bug.1 +++ b/doc/man/git-bug.1 @@ -2,17 +2,14 @@ .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" "" .SH NAME -.PP git-bug - A bug tracker embedded in Git .SH SYNOPSIS -.PP \fBgit-bug [flags]\fP .SH DESCRIPTION -.PP git-bug is a bug tracker embedded in git. .PP @@ -22,11 +19,9 @@ the same git remote you are already using to collaborate with other people. .SH OPTIONS -.PP \fB-h\fP, \fB--help\fP[=false] help for git-bug .SH SEE ALSO -.PP -\fBgit-bug-bridge(1)\fP, \fBgit-bug-bug(1)\fP, \fBgit-bug-commands(1)\fP, \fBgit-bug-label(1)\fP, \fBgit-bug-pull(1)\fP, \fBgit-bug-push(1)\fP, \fBgit-bug-termui(1)\fP, \fBgit-bug-user(1)\fP, \fBgit-bug-version(1)\fP, \fBgit-bug-webui(1)\fP, \fBgit-bug-wipe(1)\fP +\fBgit-bug-bridge(1)\fP, \fBgit-bug-bug(1)\fP, \fBgit-bug-label(1)\fP, \fBgit-bug-pull(1)\fP, \fBgit-bug-push(1)\fP, \fBgit-bug-termui(1)\fP, \fBgit-bug-user(1)\fP, \fBgit-bug-version(1)\fP, \fBgit-bug-webui(1)\fP, \fBgit-bug-wipe(1)\fP diff --git a/doc/md/git-bug.md b/doc/md/git-bug.md index a71d6dfb9..2ef0b7725 100644 --- a/doc/md/git-bug.md +++ b/doc/md/git-bug.md @@ -26,13 +26,12 @@ git-bug [flags] * [git-bug bridge](git-bug_bridge.md) - List bridges to other bug trackers * [git-bug bug](git-bug_bug.md) - List bugs -* [git-bug commands](git-bug_commands.md) - Display available commands. * [git-bug label](git-bug_label.md) - List valid labels * [git-bug pull](git-bug_pull.md) - Pull updates from a git remote * [git-bug push](git-bug_push.md) - Push updates to a git remote * [git-bug termui](git-bug_termui.md) - Launch the terminal UI * [git-bug user](git-bug_user.md) - List identities -* [git-bug version](git-bug_version.md) - Show git-bug version information +* [git-bug version](git-bug_version.md) - Print version information * [git-bug webui](git-bug_webui.md) - Launch the web UI * [git-bug wipe](git-bug_wipe.md) - Wipe git-bug from the git repository diff --git a/doc/md/git-bug_commands.md b/doc/md/git-bug_commands.md deleted file mode 100644 index bce599dd9..000000000 --- a/doc/md/git-bug_commands.md +++ /dev/null @@ -1,19 +0,0 @@ -## git-bug commands - -Display available commands. - -``` -git-bug commands [flags] -``` - -### Options - -``` - -p, --pretty Output the command description as well as Markdown compatible comment - -h, --help help for commands -``` - -### SEE ALSO - -* [git-bug](git-bug.md) - A bug tracker embedded in Git - diff --git a/doc/md/git-bug_version.md b/doc/md/git-bug_version.md index ceba8790f..a2569aff1 100644 --- a/doc/md/git-bug_version.md +++ b/doc/md/git-bug_version.md @@ -1,18 +1,46 @@ ## git-bug version -Show git-bug version information +Print version information + +### Synopsis + + +Print version information. + +Format: + git-bug <version> [commit[/dirty]] <compiler version> <platform> <arch> + +Format Description: + <version> may be one of: + - A semantic version string, prefixed with a "v", e.g. v1.2.3 + - "undefined" (if not provided, or built with an invalid version string) + + [commit], if present, is the commit hash that was checked out during the + build. This may be suffixed with '/dirty' if there were local file + modifications. This is indicative of your build being patched, or modified in + some way from the commit. + + <compiler version> is the version of the go compiler used for the build. + + <platform> is the target platform (GOOS). + + <arch> is the target architecture (GOARCH). + ``` git-bug version [flags] ``` +### Examples + +``` +git bug version +``` + ### Options ``` - -n, --number Only show the version number - -c, --commit Only show the commit hash - -a, --all Show all version information - -h, --help help for version + -h, --help help for version ``` ### SEE ALSO diff --git a/doc/usage/third-party.md b/doc/usage/third-party.md index 39a091878..39e5bbde1 100644 --- a/doc/usage/third-party.md +++ b/doc/usage/third-party.md @@ -53,7 +53,7 @@ _For a full list of the features enabled for each bridge, see the ## Getting started<a name="getting-started"></a> -1. From within a git repository, run `git bug bridge configure` to start the +1. From within a git repository, run `git bug bridge new` to start the configuration wizard 2. Choose the type of bridge you want to configure, e.g. `github` 3. Type a name for the bridge configuration. As you can configure multiple |