diff options
Diffstat (limited to 'doc/git-permalink.en.1.in')
| -rw-r--r-- | doc/git-permalink.en.1.in | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/doc/git-permalink.en.1.in b/doc/git-permalink.en.1.in new file mode 100644 index 0000000..63d8f0e --- /dev/null +++ b/doc/git-permalink.en.1.in @@ -0,0 +1,190 @@ +.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 SYNOPSIS + +\fBgit-permalink\fR [\fIOPTIONS\fR] \fIFILE\fR [\fILINENO\fR] + + +.SH DESCRIPTION + +\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. + +\fBgit-permalink\fR then uses \fBxdg-open\fR(1) to open the URL. + +.SH OPTIONS + +.TP +\fB-p\fR +Only print the web URL link to STDOUT, 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 CONFIGURATION + +.SS SUPPORTED REMOTES + +The current supported remotes are: + +.RS +.IP \(bu +git.euandreh.xyz (where git-permalink itself is hosted =p) +.IP \(bu +sourcehut +.IP \(bu +git.kernel.org +.IP \(bu +savannah +.IP \(bu +notabug +.IP \(bu +codeberg +.IP \(bu +bitbucket +.IP \(bu +pagure +.IP \(bu +gitlab +.IP \(bu +github +.RE + +Patches to add support for more source code forges are welcome! + +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. + +.SS OVERRIDES + +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). + +There are two configuration options available: + +.TP +\fBgit-permalink.template-file-commit\fR +An URL template where the name of the \fIfile\fR comes first, and the \fIcommit\fR comes second. +cgit uses this style of URL, with something like in: + +.nf + https://git.euandreh.xyz/fallible/tree/%s?id=%s +.fi + +On this example, the name of the \fIfile\fR comes first and \fIcommit\fR comes at the very end after "id=". + +.TP +\fBgit-permalink.template-commit-file\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: + +.nf + https://git.sr.ht/~sircmpwn/scdoc/tree/%s/item/%s +.fi + +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 EXAMPLES + +Open \fIsrc/fold.c\fR of a project with its origin pointing to \fIsourcehut\fR: + +.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): + +.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: + +.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 + +.P +Open file called \fI--help\fR: + +.nf + $ git permalink -- --help + Opening https://git.euandreh.xyz/non-existent-repository/tree/--help?id=470a9fa9329495cfcbef8cc5e32e3a38d3c3103e +.fi + +.SH EXIT STATUS + +.TP +.B 0 +Successful execution. + +.TP +.B 1 +Unsupported remote. +See the supported list in SUPPORTED REMOTES, and how to add custom ones in OVERRIDES. + +.TP +.B 2 +Invalid arguments. + + +.SH SEE ALSO + +\fBgit-config\fR(1) +\fBxdg-open\fR(1) + + +.SH AUTHORS + +.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 . +Use the subject "\f(CR[git\-permalink] BUG or TASK: +<description>\fR". +.IP \(bu +Browse bugs +.UR https://euandreh.xyz/git\-permalink/TODOs.html +online +.UE . +.IP \(bu +.UR https://euandreh.xyz/git\-permalink/ +Homepage +.UE . +.IP \(bu +.UR https://lists.sr.ht/~euandreh/public\-inbox?search=%5Bgit\-permalink%5D +Comments and discussions +.UE . |