diff options
Diffstat (limited to 'doc/git-permalink.1')
| -rw-r--r-- | doc/git-permalink.1 | 160 |
1 files changed, 78 insertions, 82 deletions
diff --git a/doc/git-permalink.1 b/doc/git-permalink.1 index a957d9c..97ffa4f 100644 --- a/doc/git-permalink.1 +++ b/doc/git-permalink.1 @@ -1,159 +1,155 @@ -.TH GIT-PERMALINK 1 @DATE@ "git-permalink @VERSION@ -. -. +.TH GIT-PERMALINK 1 @DATE@ "git-permalink @VERSION@" "git-permalink user manual" + + .SH NAME + git-permalink - Git extension to generate web permalinks of files in a repository -. -. + + .SH SYNOPSYS -.P + \fBgit-permalink\fR [\fI-p\fR] \fIFILE\fR [\fILINENO\fR] -. -. + + .SH DESCRIPTION -. -.P + \fBgit-permalink\fR will use Git itself to get a) the commit at \fIHEAD\fR and b) the \fIremote.origin.url\fR via \fBgit-config\fR(1), and optionally c) an URL template override. It then uses those values to build a permalink URL, with the commit included on it to ensure it is \fIpermanent\fR, and optionally the line number of the selected file. -. -.P + \fBgit-permalink\fR then uses \fBxdg-open\fR(1) to open the URL. -. + .SH OPTIONS -. + .TP -.B -p +\fB-p\fR Only print the web URL link, don't try to open it with \fBxdg-open\fR(1) or do anything else. By default this is turned off. -. + .TP \fB--help\fR, \fB-h\fR Show show help text. -. + .TP \fB--version\fR, \fB-V\fR Show version number. -. -. + + .SH OVERRIDES -.P + If you want to configure the permalink URL template for a project with an unsupported origin you can do so via \fBgit-config\fR(1). -. -.P + There are two configuration options available: -. + .TP -.B git-permalink.template-commit-file +\fBgit-permalink.template-commit-file\fR An URL template where the \fIcommit\fR comes first, and the name of the \fIfile\fR comes second. cgit uses this style of URL, with something like in: -.EX -https://git.euandreh.xyz/fallible/tree/%s?id=%s +.nf + https://git.euandreh.xyz/fallible/tree/%s?id=%s +.fi -.EE On this example, the \fIfile\fR comes first and \fIcommit\fR comes at the very end after "id=". -. + .TP -.B git-permalink.template-file-commit +\fBgit-permalink.template-file-commit\fR An URL template where the \fIcommit\fR comes first, and the name of the \fIfile\fR comes second. sourcehut uses this style of URL, with something like: -.EX -https://git.sr.ht/~sircmpwn/scdoc/tree/%s/item/%s +.nf + https://git.sr.ht/~sircmpwn/scdoc/tree/%s/item/%s +.fi -.EE On this example, the \fIcommit\fR comes first on the URL path, and the \fIfile\fR name comes at the end. -. + .P If none of those values are found by \fBgit-config\fR(1) and \fBgit-permalink\fR can't guess the URL, it exits with an error. -. -. + + .SH SUPPORTED REMOTES -.P + The current supported remotes are: -. -.IP -git.euandreh.xyz -.IP + +.RS +.IP \(bu +git.euandreh.xyz (where git-permalink itself is hosted =p) +.IP \(bu sourcehut -.IP +.IP \(bu savannah -.IP +.IP \(bu gitlab -.IP +.IP \(bu github -. -.P +.RE + Patches to add support for more source code forges are welcome! -.br + See .UR https://euandreh.xyz/git-permalink/TODOs.html#task-cebc5298-17ad-5c60-dfa5-a25b66433a3a +#task-cebc5298-17ad-5c60-dfa5-a25b66433a3a .UE for discussion and more information. -. + + .SH EXAMPLES -. -.P + Open \fIsrc/fold.c\fR of a project with its origin pointing to \fIsourcehut\fR: -.RS -.EX -$ git permalink src/fold.c 125 -Opening https://git.sr.ht/~sircmpwn/ctools/tree/fbf17d92f5ed1c38983f73df912f051ad0f9ef2d/item/src/fold.c#L125 -.EE -.RE -. -.P +.nf + $ git permalink src/fold.c 125 + Opening https://git.sr.ht/~sircmpwn/ctools/tree/fbf17d92f5ed1c38983f73df912f051ad0f9ef2d/item/src/fold.c#L125 +.fi + Generate link for lines 59 through 94 of \fInongnu/packages/clojure.scm\fR on a project hosted on \fIgitlab\fR, but only print it \fIwithout\fR opening with \fBxdg-open\fR(1): -.RS -.EX -$ git permalink -p nongnu/packages/clojure.scm 59-94 -https://gitlab.com/nonguix/nonguix/-/blob/c9d7f30bcbd3a6e3076e56a972c33963c73c4d58/nongnu/packages/clojure.scm#L59-94 -.EE -.RE -. +.nf + $ git permalink -p nongnu/packages/clojure.scm 59-94 + https://gitlab.com/nonguix/nonguix/-/blob/c9d7f30bcbd3a6e3076e56a972c33963c73c4d58/nongnu/packages/clojure.scm#L59-94 +.fi + .P Configure an URL override, and open the file \fIsrc/app_add.c\fR without selecting an specific line: -.RS -.EX -$ git config git-permalink.template-file-commit 'https://git.alpinelinux.org/apk-tools/tree/%s?id=%s' -$ git permalink src/app_add.c -Opening https://git.alpinelinux.org/apk-tools/tree/src/app_add.c?id=aeeb119fd8652c044cd5ceebce572b5c716914e3 -.EE -.RE -. -. +.nf + $ git config git-permalink.template-file-commit 'https://git.alpinelinux.org/apk-tools/tree/%s?id=%s' + $ git permalink src/app_add.c + Opening https://git.alpinelinux.org/apk-tools/tree/src/app_add.c?id=aeeb119fd8652c044cd5ceebce572b5c716914e3 +.fi + + .SH SEE ALSO -.P + \fBgit-config\fR(1) \fBxdg-open\fR(1) -. -. + + .SH AUTHORS -.P + .MT eu@euandre.org EuAndreh .ME and contributors. -. -. + + .SH BUGS + +.IP \(bu Report bugs to the .MT ~euandreh/public-inbox@lists.sr.ht mailing list .ME . -.br +Use the subject "\fC[git-permalink] BUG or TASK: <description>\fR". +.IP \(bu Browse bugs .UR https://euandreh.xyz/git-permalink/TODOs.html online .UE . -.br +.IP \(bu .UR https://euandreh.xyz/git-permalink/ Home page .UE . -.br +.IP \(bu .UR https://lists.sr.ht/~euandreh/public-inbox?search=%5Bfallible%5D Comments and discussions .UE . |