Open Git URLs Safely with git web--browse

Use git web--browse when you want Git to open a URL or a local HTML file in your browser without typing out a separate command. Allow about ten minutes. You need Git installed and a URL or readable file to open. The examples use Git 2.43.0 from the installed git-man package; later releases may add or remove browser integration details.

This helper launches another program. It does not fetch a page, create a Git commit, or change the URL. Browser choice can still matter: a graphical browser may open a window, while a text browser uses the terminal. Read the command before running it, especially when the URL came from an untrusted source.

1. Check the installed helper

Start with ordinary, read-only checks. No elevated privileges are needed:

$ git --version
git version 2.43.0
$ man git-web--browse

The command is exposed through Git, so use git web--browse rather than relying on the helper's location in Git's private executable directory. Its shape is:

$ git web--browse [options] URL-or-file ...

Pass one or more URLs or file paths. The helper attempts to display them in new tabs on an already running browser where that browser supports the behaviour. A successful launch does not prove the page loaded or the target was safe.

Checkpoint: you have confirmed the Git version and can identify the target you intend to open.

2. Choose a browser for one command

Use --browser or its short form -b when you want a temporary choice. The installed manual lists Firefox, Chromium and its aliases, Konqueror, Opera, several text browsers, and xdg-open, among others. This example is suitable for a graphical Linux desktop with Firefox installed:

$ git web--browse --browser=firefox 'https://git-scm.com/docs/git-web--browse'

Use --tool or -t as an equivalent spelling:

$ git web--browse -t firefox 'https://git-scm.com/docs/git-config'

Quote URLs and paths as a habit: it prevents shell characters such as &, spaces and parentheses from being interpreted by the shell. The helper accepts several targets, so a single invocation can open related pages:

$ git web--browse --browser=firefox \
    'https://git-scm.com/docs/git' \
    'https://git-scm.com/docs/git-config'

If Firefox is not installed, the command fails before opening anything useful. Substitute a browser that is installed on your machine; do not use sudo to launch a desktop browser.

3. Open a local HTML file

A file path is accepted alongside a URL. Use an absolute path when a script, editor or changed working directory could make a relative path ambiguous:

$ test -r "$PWD/report.html" && echo 'readable'
readable
$ git web--browse --browser=firefox "$PWD/report.html"

The first command is a read check. If it prints nothing, inspect the path and permissions rather than adding elevated privileges. Warning: a file containing active content can still be dangerous when opened in a browser. Treat reports generated from untrusted input as untrusted documents.

Outside a graphical session, the default candidates are text browsers such as w3m, elinks, links and lynx. Git chooses from the candidates it can find. Make the choice explicit when the default is distracting or unsuitable:

$ git web--browse --browser=w3m 'https://git-scm.com/docs/git-web--browse'

Checkpoint: the chosen browser matches the session you are in, and the target is readable or correctly quoted.

4. Set a personal default

For a preference that should follow you between repositories, set web.browser in your global Git configuration. This changes your user configuration, so it does not need root access:

$ git config --global web.browser firefox
$ git config --global --get web.browser
firefox
$ git web--browse 'https://git-scm.com/docs/git-web--browse'

Git also reads a configuration name supplied with --config or -c. That is useful when different workflows need different choices, without changing the global default:

$ git config --global web.browser firefox
$ git -c work.browser=w3m web--browse --config=work.browser 'https://example.com/work'

Here work.browser is supplied temporarily and contains the browser name w3m. The option selects the configuration variable; it does not name the browser directly.

To undo the global setting and return to Git's automatic selection, remove only that key:

$ git config --global --unset web.browser

If the key did not exist, Git reports an error and changes nothing. Check first with git config --global --get web.browser if you need a quiet script.

5. Add a custom command only when you trust its input

Warning: for a browser or wrapper not in the built-in list, define browser.<tool>.cmd. Git passes the target arguments to that command through a shell evaluation. This is powerful and security-sensitive: shell metacharacters in a target can affect the command. Do not use this feature with untrusted URLs or file names unless your wrapper handles them safely.

First test a custom command without changing your files or persistent configuration. Git's temporary -c options last for one invocation:

$ git -c browser.capture.cmd='printf "opened: %s\\n" "$@"' \
    web--browse --browser=capture 'https://example.com/docs'
opened: https://example.com/docs

The output is from printf, not from a browser. It proves that Git selected the custom tool and passed the URL as an argument. Keep a real wrapper simple, quote its arguments, and avoid concatenating a target into another shell command.

For a persistent custom wrapper, store its command in a global setting and inspect it afterwards. This example assumes the wrapper already exists at the stated path:

$ git config --global browser.my-browser.path /usr/local/bin/my-browser
$ git config --global browser.my-browser.cmd /usr/local/bin/my-browser
$ git config --global --get browser.my-browser.cmd
/usr/local/bin/my-browser
$ git web--browse --browser=my-browser 'https://example.com/docs'

Use browser.<tool>.path when the program itself is a supported browser. Use browser.<tool>.cmd when Git must run a custom command. Remove both experimental settings with the matching --unset commands, for example git config --global --unset browser.my-browser.cmd and git config --global --unset browser.my-browser.path.

6. Diagnose failures without guessing

A missing URL or file produces usage text:

$ git web--browse --browser=firefox
usage: git web--browse [--browser=browser|--tool=browser] [--config=conf.var] url/file ...

An unknown browser name is rejected unless a matching custom command has been configured:

$ git web--browse --browser=definitely-not-a-browser 'https://example.com/docs'
Unknown browser 'definitely-not-a-browser'.

If Git says a browser is unavailable, check it without launching it:

$ command -v firefox
/usr/bin/firefox

No output means that command is not on your PATH. Choose an installed browser or set its full path with browser.<tool>.path. Do not edit Git's system files to fix a user preference, and do not run the helper as root merely because a browser is missing.

Done means