git-cola: 高效的Git GUI

Git Cola是一款功能强大且用户界面流畅的Git GUI。

git clone https://github.com/git-cola/git-cola.git

• 屏幕截图

• 下载

文档

• 键盘快捷键

• HTML文档

• Git Cola文档

• Git DAG文档

• 贡献指南

需求

构建

• Sphinx用于生成文档。

运行时

• Git 2.2.0或更高版本。

• Python 3.6或更高版本。

• QtPy 2.0.0或更高版本。

Git Cola使用QtPy，因此您可以通过设置环境变量QT_API为pyqt6、pyqt5或pyside2来选择PyQt6、PyQt5和PySide2。默认情况下，qtpy为pyqt5，如果未安装pyqt5，则回退到pyqt6和pyside2。

以下任一Python Qt库必须安装

• PyQt5 / PyQt6 5.9或更高版本是必需的。通过QtPy也支持Qt 6.2或更高版本。

• PySide2 5.12.0或更高版本。

可选功能

Git Cola 在以下 Python 模块安装时将启用附加功能。

Send2Trash 使“发送到回收站”功能支持跨平台。(源代码)

notify_py 使桌面通知功能成为可能。(源代码)

pyobjc 在 macOS 上启用特定于 macOS 的应用程序主题。(源代码)

安装

安装 Git Cola 有几种方法，但您无需安装 Git Cola 即可运行它。

Git Cola 设计为直接从其源代码树运行。安装是可选的。

从源代码

运行最新版本的 Git Cola 的推荐方法是使用您发行版的包管理器安装其 PyQt 依赖项，然后直接从源代码运行 ./bin/git-cola。

在 Debian / Ubuntu 系统上安装 PyQt 依赖项

Git Cola 与 PyQt5 或 PyQt6 都兼容，因为它使用 qtpy 库来确保 PyQt 兼容性。

PyQt5

在新版 Debian/Ubuntu 版本上，您可以安装单个包以从源代码运行。

sudo apt install python3-qtpy

如果您使用的是没有提供 python3-qtpy 的旧版本，则可以直接安装以下包。

sudo apt install python3-pyqt5 python3-pyqt5.qtopengl python3-pyqt5.qtwebengine python3-pyqt5.qtsvg

PyQt6

如果您想使用 PyQt6 生态系统与 Git Cola 一起使用，则可以安装这些包而不是 PyQt5。

sudo apt install python3-pyqt6 python3-pyqt6.qtsvg python3-pyqt6.qtwebengine

此时，您应该能够从源代码树启动 ./bin/git-cola，并且没有更多的事情要做。

以下更详细的说明将介绍如何从 PyPI 安装 Git Cola 或如何将其安装到与源代码树不同的位置。

Linux

Linux！您的发行版可能已经打包了 git-cola。如果没有，请向您的发行版提交错误报告 ;-)

Arch

可在 AUR 中找到。

Debian, Ubuntu

apt install git-cola

Fedora

dnf install git-cola

Gentoo

emerge git-cola

OpenSUSE, SLE

zypper install git-cola

Slackware

可在 SlackBuilds.org 中找到。

Ubuntu

此处 可查看 Ubuntu 仓库中可用的版本。

FreeBSD

# Install from official binary packages
pkg install -r FreeBSD devel/git-cola

# Build from source
cd /usr/ports/devel/git-cola && make clean install

使用 pip 在 PyPI 上安装到 Python 虚拟环境

重要：切勿在 Python 虚拟环境或作为 root 运行 pip install 或 garden install！

重要：如果您所在的是 PyQt6 或 PyQt5 可通过包管理器获取的 Linux 发行版，则强烈建议使用系统包管理器安装这些依赖项。请参阅上方的说明以获取详细信息。

安装最新发布版本的一种方法是使用 venv（虚拟环境）和 pip。这将从 pypi.org 安装 git-cola。

python3 -m venv --system-site-packages env3
./env3/bin/pip install git-cola
./env3/bin/git-cola

将 env3/bin 目录添加到您的 PATH 或从 PATH 中的某处创建 bin/git-cola 的符号链接，例如 ~/.local/bin/git-cola，然后您就可以像其他内置的 git 命令一样启动 Git Cola

git cola
git dag

从源代码安装到 Python 虚拟环境

如果您没有安装 PyQt，则最简单的方法是使用 Python 虚拟环境，并以“可编辑”模式安装 Git Cola 到其中。

此安装方法允许您通过运行 git pull 来升级 Git Cola。

# Create a virtualenv called "env3" and activate it.
python3 -m venv --system-site-packages env3

# Install PyQt and (optional) extra packages to enable all features.
./env3/bin/pip install --editable '.[extras,pyqt6]'

# Run Git Cola via the "git-cola" Git subcommand.
source env3/bin/activate
git cola

如果您将 env3/bin（或其软链接到 env3/bin/git-cola） 添加到您的 $PATH 中，那么您就可以像使用内建的 git 命令一样运行 git cola（例如，在运行 "deactivate" 后或打开新 shell 时）。

从源码独立安装

运行 garden -D prefix=$HOME/.local install 将在您的 $HOME/.local 目录中安装 Git Cola（例如，$HOME/.local/bin/git-cola、$HOME/.local/lib 等）。

此安装方法假定 qtpy 和 PyQt* 依赖项已预先安装。

Garden 脚本还支持 DESTDIR 以支持为 Linux 软件包管理器创建软件包。

garden -D DESTDIR=/tmp/stage -D prefix=/usr/local install

如果您没有 garden，则可以使用 make 代替。Makefile 支持使用传统的 DESTDIR 和 prefix 变量进行分阶段安装。

make DESTDIR=/tmp/stage prefix=/usr/local install

macOS

对于大多数最终用户，我们建议使用 Homebrew 或按上述方法安装到 Python 虚拟环境中。

您可以使用与上述相同的步骤从源码安装 Git Cola。

Homebrew

安装 Git Cola 的简单方法是使用 Homebrew 。使用 Homebrew 安装 git-cola 脚本。

brew install git-cola

如果您使用 Homebrew 进行安装，则可以在此步骤停止。您不需要克隆存储库或进行其他操作。

git-cola.app

如果您已通过 pip 或 brew 安装了所有依赖项，则可以构建用于 /Applications 的 shell git-cola.app 应用程序包包装器。

如果您想构建用于 /Applications 的 git-cola.app 包，请运行以下命令

garden macos/app

您需要定期重建应用程序包装器，因为 Python 升级时。

更新 macOS 和 Homebrew

更新 macOS 有时会导致 Homebrew 管理的软件损坏。

如果您更新了 macOS 且 Git Cola 停止工作，那么您可能需要重新安装 Git Cola 的依赖项。

按照以下说明从头开始重新安装可以解决问题。

brew update

brew uninstall git-cola
brew uninstall pyqt
brew uninstall pyqt@5
brew autoremove

brew install git-cola

Windows

重要提示：如果您有 64 位机器，请只安装 64 位版本。不要混合 32 位和 64 位版本。

下载并安装以下内容

• Git for Windows

• Git Cola

安装完成后，您可以从开始菜单运行 Git Cola。

有关更多详细信息，请参阅下面的 "Windows（继续）"。

如果您想使用 winget 安装 Git Cola，请运行以下命令

winget install git-cola.git-cola

由于尚无依赖项解析，您必须使用以下命令安装 Git

winget install Git.Git

附加组件

Git Cola 附带了一个名为 git-cola-sequence-editor 的交互式变基编辑器。git-cola-sequence-editor 用于在变基时重新排序和选择提交。通过 "变基" 菜单或 git cola rebase 子命令启动交互式变基以使用 git-cola-sequence-editor。

git cola rebase @{upstream}

您可以通过告诉 git rebase 使用它作为其编辑器来独立于 git cola 启动 git-cola-sequence-editor，通过 GIT_SEQUENCE_EDITOR 环境变量。

export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor"
git rebase -i @{upstream}

Shell 完成脚本

bash 和 zsh 的 shell 完成脚本可用。每个脚本都包含有关如何安装和激活完成的说明。

• bash 完成脚本

• zsh 完成脚本

Git Cola 子命令

git-cola 命令公开了各种子命令，允许您快速启动 git-cola 界面内可用的工具。例如，git cola find 将启动文件查找器，而 git cola grep 将启动 grep 工具。

有关命令的完整列表，请参阅 git cola --help-commands。

$ git cola --help-commands
usage: git-cola [-h]

                {cola,am,archive,branch,browse,config,
                 dag,diff,fetch,find,grep,merge,pull,push,
                 rebase,remote,search,stash,tag,version}
                ...

valid commands:
  {cola,am,archive,branch,browse,config,
   dag,diff,fetch,find,grep,merge,pull,push,
   rebase,remote,search,stash,tag,version}

    cola                start git-cola
    am                  apply patches using "git am"
    archive             save an archive
    branch              create a branch
    browse              browse repository
    config              edit configuration
    dag                 start git-dag
    diff                view diffs
    fetch               fetch remotes
    find                find files
    grep                grep source
    merge               merge branches
    pull                pull remote branches
    push                push remote branches
    rebase              interactive rebase
    remote              edit remotes
    search              search commits
    stash               stash and unstash changes
    tag                 create tags
    version             print the version

开发

如果您已安装 Git Cola 的依赖项，则如果提供源代码，则可以将其作为 Python 模块启动 cola。

python -m cola
python -m cola dag

以下命令应在开发过程中运行

# Run the unit tests
$ garden test

# Run tests and doc checks
$ garden check

# Run tests against multiple python interpreters using tox
$ garden tox

测试套件位于 test 目录中。

使用 GitHub Actions 自动对提交和拉取请求进行代码质量测试。

在更新翻译时，在提交之前自动格式化 cola/i18n/*.po 文件。

$ garden po

提交补丁时，请参阅 贡献指南。

包装说明

Git Cola 使用 setuptools 将其模块安装到默认的 Python 站点包目录中（例如 lib/python3.7/site-packages）。

虽然最终用户可以使用 pip install git-cola 安装 Git Cola，但发行版打包者应使用 garden -D prefix=/usr install 进程。Git Cola 的 Garden 菜单将 pip install --prefix=<prefix> 包装起来，以提供友好的包装 garden install 目标。

Windows（继续）

Microsoft Visual C++ 2015 可再分发包

Git Cola 的早期版本可能未包含 vcruntime140.dll，并且可能无法在缺少此 DLL 的机器上运行。

要修复此问题，请下载 Microsoft Visual C++ 2015 可再分发包 并安装它

Git Cola v4.0.0 及更高版本包含此 DLL，无需单独安装。

开发

为了在 Windows 上开发 Git Cola，您需要安装 Python3 和 pip。使用 pip install PyQt5 安装 PyQt5 以使 PyQt5 绑定可用于 Python。

安装完成后，您可以使用 python.exe 从源树中直接运行。例如，从 Git Bash 终端

/c/Python39/python.exe ./bin/git-cola

多个 Python 版本

如果您安装了多个 Python 版本，则 contrib/win32/cola 启动器脚本可能会选择较新的版本，而不是已安装 PyQt 的 Python。为了解决此问题，可以将 git 配置变量 cola.pythonlocation 设置为告诉 cola Python 的位置。例如

git config --global cola.pythonlocation /c/Python39

构建 Windows 安装程序

使用以下方法构建 Windows 安装程序

• Pynsist.

• NSIS 也需要。

要使用 Pynsist 构建安装程序，请运行

./contrib/win32/run-pynsist.sh

这将生成位于 build/nsis/ 的安装程序。

Windows "历史浏览器" 配置升级

如果您从旧版本的 Git Cola 升级到 Windows，则可能需要配置历史浏览器。

gitk 最初是默认的历史浏览器，但由于 gitk 是外壳脚本，因此无法直接在 Windows 上启动。

如果您配置为使用 gitk，则将配置更改为通过 Windows 上的 sh.exe 进行。同样，如果我们想使用 git-dag，则必须通过 python.exe 进行。

如果您想使用 gitk 作为历史浏览器，请打开首选项屏幕，将历史浏览器命令更改为

"C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk

git-dag 已在 v2.3 中成为 Windows 上的默认历史浏览器，因此新用户无需进行任何配置。