.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

\fBgit-permalink\fR [OPTIONS] \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, 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

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-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:

.nf
	https://git.euandreh.xyz/fallible/tree/%s?id=%s
.fi

On this example, the \fIfile\fR comes first and \fIcommit\fR comes at the very end after "id=".

.TP
\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:

.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 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
savannah
.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.


.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


.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 "\fC[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 .