Fossil Forum

#!/bin/bash
# ==============================================================================
# JETBRAINS-FOSSIL: The Fossil-not-Plugin for PhpStorm
# Copyright (c) 2026 by LowRess
#
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at https://mozilla.org/MPL/2.0/.
# ==============================================================================
# INSTALLATION & SETUP:
# 1. Save this script as ~/bin/jetbrains-fossil.sh on your local IDE machine.
# 2. Make it executable: chmod +x ~/bin/jetbrains-fossil.sh
# 3. Create a symlink for Java visibility:
#   sudo ln -s ~/bin/jetbrains-fossil.sh /usr/local/bin/jetbrains-fossil
# 4. Configure your connection options below (under CONNECTION CONFIGURATION).
# 5. Adjust the visibility options in the COMMANDS definition to your liking.
#   Be careful NOT to remove any configured 'u' flag!
# 6. Initialize the environment: jetbrains-fossil init (Windows users: see NOTE #4)
#   -> Automatically provisions the "Fossil" IDE tools menu suite.
#   -> Dynamically populates the "Fossil Changes" shared project scope.
# 7. Customize your interface (Optional): in PhpStorm
#   - Right-click the main top toolbar -> Customize Toolbar.
#   - Navigate to Main Toolbar > Left -> Add... ->
#   - Type in "Fossil" to navigate to External Tools > Fossil.
#   - Tip: Grab the Fossil logo (fossil3.gif), convert to PNG or SVG, and assign it
#   - move the new tool where you want it - I replaced "VCS group".
#   - add keyboard shortcuts where applicable.
# ==============================================================================
# NOTES
#   1. works great on my system (Linux, SSH mode); no guarantees for yours!
#   2. tested with PhpStorm 2026.1; but may also work with other JetBrains products.
#      reconfigure IDE_NAME to find out - and let me know!
#   3. some of the commands may be configured incorrectly or incompletely.
#      If you find errors, please let me know.
#   4. Windows users: put this script anywhere in your path, wrap
#      git bash, WSL or MSYS2 around it, and run with 'init' argument.
#   5. Should you alter this script, PLEASE keep the code as tidy as it is - and share it!
# ==============================================================================

# ==============================================================================
# CONNECTION CONFIGURATION
# ==============================================================================
SRV="localhost"             # name or IP address of your development server; may be empty for "localhost"
KEY="-i ~/.ssh/id_ed25519"  # "-i "+path to your private SSH key file
# ==============================================================================
IDE_NAME="PhpStorm"

# ==============================================================================
# COMMAND CONFIGURATION
# ==============================================================================
flag() { case $1 in
    m) a="showInMainMenu";;
    c) a="showInContextMenu";;
    t) a="showInToolwindowContextMenu";;
    p) a="showInProjectConnectionContextMenu";;
    u) a="synchronizeAfterRun";;
    *) echo "skipping unknown flag '$1'" >&2;return 1;;
esac; }

declare -a COMMANDS=(
    "add:cpu:\$FilePathRelativeToProjectRoot\$"
    "rm:cpu:\$FilePathRelativeToProjectRoot\$"
    "addremove:umpt:\$FilePathRelativeToProjectRoot\$" # Toolwindow, Main, Project + IDE Sync

    "status:mcut:"                                  # combines info and changes
    "info::"                                        # Info works great on the current file (Context) or globally
    "changes:u:"                                    # Global changes overview
    "timeline:mt:"                                  # Global project timeline
    "diff:mct:\$FilePathRelativeToProjectRoot\$"    # Diff for the selected file or global diff
#   "gdiff:mtc:\$FilePathRelativeToProjectRoot\$"   # Graphical diff
#   "ls:mt:"                                        # List files

    "commit:mcu:"                                   # Sync, show in Main Menu, Context Menu
#   "branch:mt:"                                    # Branch management
#   "push:mt:"                                      # Push usually runs globally from Main or Toolwindow
#   "pull:mtu:"                                     # Pull needs Sync after run to update the IDE state
    "sync:mtu:"                                     # Sync bidirectional. Needs IDE Sync after run

    "update:mtu:\$SelectedText\$"                   # Update to a version. SelectedText could be the tag/branch
    "checkout:mtu:\$SelectedText\$"                 # Checkout version. Needs IDE Sync
    "merge:mtu:\$SelectedText\$"                    # Merge branch. Needs IDE Sync

    "undo:mtu:"                                     # Undo local changes. Needs IDE Sync
    "redo:mtu:"                                     # Redo local changes. Needs IDE Sync
)

# probably never supported:
#fossil clone URL repository-filename
# definitely never supported:
#fossil init repository-filename && mkdir -p ~/src/project/trunk && cd ~/src/project/trunk && fossil open repository-filename && fossil add bootstrap.php index.php && fossil commit

# ==============================================================================
# THE ACTUAL CODE
# ==============================================================================
error() { t=""; [ -n "$2" ] && t=" on $2"; echo "$0$t: $1" >&2; exit 1; }
fos() {
    if [ -z "$SRV" ]; then
        (cd "$DIR" && fossil "$@")
    else
        ssh $KEY "$SRV" "sh -s" <<EOF
cd "$DIR" && fossil "$@"
EOF
    fi || error "fossil $* failed" "$SSH_TARGET"
}

DF=".idea/deployment.xml"; [ ! -f "$DF" ] && error "$DF not found";
DIR=$(grep -oP 'deploy="\K[^"]+' "$DF" | head -n 1)
[ -z "$DIR" ] && error "deploy target in $DF is empty"
[ -z "SRV" ] && [ ! -d "$DIR" ] && error "'$DIR' does not exist"

if [ -z "$1" ]; then error "requires at least one argument"
elif [ "init" = "$1" ]; then
    # INIT setup: compile XML
    xml() {
        IFS=: read -r cmd flags args <<<"$1"
        name="${2:-$(tr '[:lower:]' '[:upper:]' <<<${cmd:0:1})${cmd:1}}"
#       name="${2:-${cmd^}}" in bash 4
        attr="";[ -n "$3" ] && attr=" description=\"$3\""
        for (( i=${#flags}; i--; )); do flag "${flags:$i:1}" && attr+=" $a=\"true\""; done
        echo '
    <tool name="'"$name"'"'"$attr"' useConsole="true"><exec>
        <option name="COMMAND" value="jetbrains-fossil" />
        <option name="PARAMETERS" value="'"$cmd $args"'" />
        <option name="WORKING_DIRECTORY" value="$ProjectFileDir$" />
    </exec></tool>'
    }

    OUT='<toolSet name="Fossil">'"$(xml 'scope:mpu:' 'Scope Sync' 'Sync remote changes to local scope')"
    for item in "${COMMANDS[@]}"; do OUT+="$(xml "$item")"; done
    OUT+=$'\n</toolSet>'

    # INIT exploit: locate active JetBrains configuration and flush generated output to disk
    JB=$(find ~/.config/JetBrains -maxdepth 1 -type d -name "$IDE_NAME*" 2>/dev/null | sort -V | tail -n 1)
    [ -z "$JB" ] && error "$IDE_NAME config directory not found."
    TX="$JB/tools/Fossil.xml"; mkdir -p "$(dirname "$TX")"; echo "$OUT" > "$TX"

    echo "Successfully installed tool definitions to $TX."
    "$0" scope
    echo "Please restart $IDE_NAME to load the new menus."
elif [ "scope" = "$1" ]; then
    # SCOPE setup: grab fossil changes and reformat to JetBrains scope pattern"
    OUT=$(fos changes) || exit 1
    OUT=$(awk '{printf "file:%s||", $2}' <<< "$OUT" | sed 's/||$//')
    # SCOPE exploit: save $OUT to scope file
    mkdir -p ".idea/scopes"
    echo '<component name="DependencyValidationManager">
    <scope name="Fossil Changes" pattern="$OUT" />
</component>' > ".idea/scopes/Fossil_Changes.xml"
    echo "Fossil Project Scope Successfully (Re)built."
else
    # if CMD is defined -> Fossil call
    for item in "${COMMANDS[@]}"; do if [[ "$item" == "$1:"* ]]; then
        fos "$@"
        # if update flag is set -> rebuild scope
        CF="${item#*:}"; CF="${CMD_FLAGS%:*}"; [[ "$CF" == *u* ]] && "$0" scope
        exit 0
    fi; done
    error "unsupported command '$1'"
fi