Metadata-Version: 2.4
Name: git-weblink
Version: 1.0.0
Summary: Produce web link to a commit, file, or line in a repo
Author-email: Dmitry Gerasimov <di.gerasimov@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/dseight/git-weblink
Project-URL: Issues, https://github.com/dseight/git-weblink/issues
Keywords: git
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: black>=22.8.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# git-weblink

This is a command for git that gives you a web link to a commit, file or
line(s) in file.

Works with Python 3.6+. No external dependencies.

## Setup

### With pip

Just install it with pip:

    pip install git-weblink

### Manual setup

Use manual setup in case you don't want to use pip.

Download `git_weblink.py`, rename it to `git-weblink` (without the `.py`
extension) and make it globally available by adding a path to it to the `PATH`
variable in your shell. This will make it appear as a git command, and you'll
be able to run it like so:

    git weblink

## Usage

`git-weblink` can generate various links:
- link to a commit
- link to a file
- link to a line or a line range in file

Links to file or line are always generated as permalinks. There is no option to
override this behavior.

### Link to a commit

    $ git weblink -r HEAD
    https://github.com/torvalds/linux/blob/adc218676eef25575469234709c2d87185ca223a/HEAD

    $ git weblink -r v6.13
    https://github.com/torvalds/linux/commit/d6cb6a3d99adf559a0a404d086f61ee3be866f86

    $ git weblink -r 35ff3b0f4596c82ec0a3e1cc43e2a85f5e976023
    https://github.com/torvalds/linux/commit/35ff3b0f4596c82ec0a3e1cc43e2a85f5e976023

### Link to a file

When no revision specified, the link will be generated for the current `HEAD`.
This means, if you are on a commit that is not pushed yet, the link will be
invalid!

    $ git weblink include/linux/kernel.h
    https://github.com/torvalds/linux/blob/adc218676eef25575469234709c2d87185ca223a/include/linux/kernel.h

Here's a link to the file on a specific revision:

    $ git weblink --rev v6.18 include/linux/kernel.h
    https://github.com/torvalds/linux/blob/f7b88edb52c8dd01b7e576390d658ae6eef0e134/include/linux/kernel.h

### Link to a line or a line range

A link to a line or to a line range can be generated by adding a line number or
a line range after the file name:

    $ git weblink include/linux/kernel.h:42
    https://github.com/torvalds/linux/blob/adc218676eef25575469234709c2d87185ca223a/include/linux/kernel.h#L42

    $ git weblink include/linux/compiler.h:248-293
    https://github.com/torvalds/linux/blob/adc218676eef25575469234709c2d87185ca223a/include/linux/compiler.h#L248-L293

### Integration with (neo)vim

The easiest way to integrate it to vim is to copy-paste the following snippet
into your `~/.vimrc` (or `~/.config/nvim/init.vim` for neovim):

```vim
function! s:GitWeblink(line1, line2)
    let l:range = a:line1
    if a:line1 != a:line2
        let l:range .= "-" . a:line2
    endif
    let l:file_with_range = expand('%:.') . ":" . l:range
    let l:cmd = "git weblink -n " . shellescape(l:file_with_range)
    let l:link = system(l:cmd)
    " Copy the link (without a newline) to the system clipboard
    let @+ = trim(l:link)
endfunction

" Run :GitWeblink on a range to get a link
command! -range=% GitWeblink call <SID>GitWeblink(<line1>, <line2>)

" Map GitWeblink for visual mode on "L" key
xmap <silent> L :GitWeblink<cr>
```

## Configuration

### Host-specific links

Builtin configuration includes configs for some commonly used hosts (such as
github.com, gitlab.com, etc.). But if you are hosting your own git forge, or
you are using some corporate repo that you don't want to add into the source,
you can put configuration for it into your `~/.gitconfig`.

One option is to use preset for some well-known service:

    [weblink "https://your-gitlab-instance.com"]
        preset = "gitlab"

Available presets are:
- forgejo
- github
- gitlab

Or, in case of non-standard configuration of the service, or in case of usage
of some less known forge, explicitly write url patterns:

    [weblink "https://your-forge.com"]
        commit = "{host}/{repo}/commit/{rev}"
        file = "{host}/{repo}/blob/{rev}/{path}"
        line = "{host}/{repo}/blob/{rev}/{path}#L{line}"
        range = "{host}/{repo}/blob/{rev}/{path}#L{range_begin}-L{range_end}"

Look at `HOST_CONFIGS` in `git-weblink` source for some references.

Variables also can be changed with `sub()` function. E.g., if you need to
remove the string `"git/"` from the beginning of the `repo` variable, just do
something like this:

    [weblink "https://your-forge.com"]
        commit = "{host}/{sub(repo, '^git/', '')}/commit/{rev}"

### Remote

Another thing to configure is the default remote. Most users don't need to do
anything about this, as by default `origin` will be used as a remote.

But if you have multiple remotes in your repo, and often want to get a link to
a remote named other than `origin`, you can either provide the remote name
explicitly:

    git weblink --remote myremote ...

or you can set the default remote by running this git command:

    git config --local weblink.remote myremote

and now `myremote` will be used by default, without need to provide it
explicitly.

For example, consider the following setup for a Linux repo:

    $ git remote -v
    beagleboard     https://github.com/beagleboard/linux.git (fetch)
    beagleboard     https://github.com/beagleboard/linux.git (push)
    stable  https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git (fetch)
    stable  https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git (push)

and let's say that by default you want to get links to `stable` repo. In this case just run this:

    git config --local weblink.remote stable

and now links will be generated to Linux stable repo:

    $ git weblink -r v6.12.63 Makefile
    https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/Makefile?id=6d8ac7def7031521a56bae29cadece53987bec3c

## License

Licensed under [MIT License](LICENSE).
