From 4b087f910e70169cec6d34857ae8f06245186777 Mon Sep 17 00:00:00 2001 From: David Aguilar Date: Tue, 8 Feb 2022 23:39:06 -0800 Subject: [PATCH] requirements: add PyQt5 and start reworking the README for Python3 Drop references to Python2 from the README. Start preparing for the upcoming distutils removal by trimming bits we do not need and removing references to older dependencies. We will also be upgrading to a newer QtPy, which no longer supports PyQt4, so we can stop mentioning it in our documentation. Related-to: #1201 Signed-off-by: David Aguilar --- README.md | 235 +++++++++++++++++------------------------- requirements/requirements.txt | 28 ++--- 2 files changed, 105 insertions(+), 158 deletions(-) rewrite requirements/requirements.txt (79%) diff --git a/README.md b/README.md index 6fd1a2ca..148803ca 100644 --- a/README.md +++ b/README.md @@ -1,97 +1,75 @@ # git-cola: The highly caffeinated Git GUI - git-cola is a powerful Git GUI with a slick and intuitive user interface. +Git Cola is a powerful Git GUI with a slick and intuitive user interface. - Copyright (C) 2007-2020, David Aguilar and contributors + git clone https://github.com/git-cola/git-cola - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 2 of the License, or - (at your option) any later version. +[![Build status](https://github.com/git-cola/git-cola/actions/workflows/main.yml/badge.svg?branch=main&event=push)](https://github.com/git-cola/git-cola/actions/workflows/main.yml) - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. +* [Screenshots](https://git-cola.github.io/screenshots.html) - You should have received a copy of the GNU General Public License - along with this program. If not, see . +* [Downloads](https://git-cola.github.io/downloads.html) -## SCREENSHOTS -Screenshots are available on the -[git-cola screenshots page](https://git-cola.github.io/screenshots.html). +# Documentation -## DOWNLOAD - - apt install git-cola +* [HTML documentation](https://git-cola.readthedocs.io/en/latest/) -New releases are available on the -[git-cola download page](https://git-cola.github.io/downloads.html). +* [Git Cola documentation](share/doc/git-cola/git-cola.rst) -## FORK +* [Git DAG documentation](share/doc/git-cola/git-dag.rst) - git clone git://github.com/git-cola/git-cola.git +* [Keyboard shortcuts](https://git-cola.github.io/share/doc/git-cola/hotkeys.html) -[![git-cola build status](https://github.com/git-cola/git-cola/actions/workflows/main.yml/badge.svg?branch=main&event=push)](https://github.com/git-cola/git-cola/actions/workflows/main.yml) +* [Contributing guidelines](CONTRIBUTING.md) -[git-cola on github](https://github.com/git-cola/git-cola) -[git-cola google group](https://groups.google.com/group/git-cola/) +# Requirements +## Build -# NUTRITIONAL FACTS +* [Sphinx](http://sphinx-doc.org/) is used to generate the documentation. -## ACTIVE INGREDIENTS +## Runtime -* [git](https://git-scm.com/) 1.6.3 or newer. +* [Git](https://git-scm.com/) 2.2.0 or newer. -* [Python](https://python.org/) 2.6 or newer (Python 2+3 compatible). +* [Python](https://python.org/) 3.6 or newer. * [QtPy](https://github.com/spyder-ide/qtpy) 1.1.0 or newer. -* [argparse](https://pypi.python.org/pypi/argparse) 1.1 or newer. - argparse is part of the stdlib in Python 2.7; install argparse separately if - you are running on Python 2.6. - -* [Sphinx](http://sphinx-doc.org/) for building the documentation. - -git-cola uses QtPy, so you can choose between PyQt4, PyQt5, and -PySide by setting the `QT_API` environment variable to `pyqt4`, `pyqt5` or -`pyside` as desired. `qtpy` defaults to `pyqt5` and falls back to `pyqt4` -if `pyqt5` is not installed. +Git Cola uses QtPy, so you can choose between PyQt5 and PySide2 by setting +the `QT_API` environment variable to `pyqt5` or `pyside2` as desired. +`qtpy` defaults to `pyqt5` and falls back to `pyside2` if `pyqt5` is not installed. Any of the following Python Qt libraries must be installed: -* [PyQt4](https://www.riverbankcomputing.com/software/pyqt/download) - 4.6 or newer - * [PyQt5](https://www.riverbankcomputing.com/software/pyqt/download5) - 5.2 or newer + 5.6 or newer. -* [PySide](https://github.com/PySide/PySide) - 1.1.0 or newer +* [PySide2](https://github.com/PySide/PySide) + 5.11.0 or newer. Set `QT_API=pyqt4` in your environment if you have both versions of PyQt installed and want to ensure that PyQt4 is used. -## ADDITIVES +## Optional Features -git-cola enables additional features when the following +Git Cola enables additional features when the following Python modules are installed. [send2trash](https://github.com/hsoft/send2trash) enables cross-platform "Send to Trash" functionality. -# BREWING INSTRUCTIONS -## RUN FROM SOURCE +# How to Install Git Cola -You don't need to install git-cola to run it. -Running git-cola from its source tree is the easiest -way to try the latest version. +## Run from Source - git clone git://github.com/git-cola/git-cola.git +You can run Git Cola directly from its source tree and try the latest version +without needing to `make install` it. + + git clone https://github.com/git-cola/git-cola cd git-cola ./bin/git-cola ./bin/git-dag @@ -105,85 +83,75 @@ You can also start `cola` as a Python module if Python can find it. Having git-cola's `bin/` directory in your path allows you to run `git cola` like a regular built-in Git command: - # Replace "$PWD/bin" with the path to git-cola's bin/ directory - PATH="$PWD/bin":"$PATH" + # Replace "$HOME/git-cola/bin" with the path to git-cola's bin/ directory + PATH="$HOME/git-cola/bin":"$PATH" export PATH git cola git dag The instructions below assume that you have git-cola present in your -`$PATH`. Replace "git cola" with "./bin/git-cola" as needed if you'd like to -just run it in-place. +`$PATH`. Replace `git cola` with `./bin/git-cola` to run it in-place. -# DOCUMENTATION +## Python Virtual Environments -* [HTML documentation](https://git-cola.readthedocs.io/en/latest/) +If you don't have PyQt installed then the easiest way to get it is to use a Python +virtualenv and install PyQt5 inside of it. -* [git-cola manual](share/doc/git-cola/git-cola.rst) + python3 -m venv env3 + ./env3/bin/pip install -r requirements/requirements.txt -* [git-dag manual](share/doc/git-cola/git-dag.rst) +You can then run Git Cola using the `env3` virtualenv. -* [Keyboard shortcuts](https://git-cola.github.io/share/doc/git-cola/hotkeys.html) + ./env3/bin/python ./bin/git-cola -* [Contributing guidelines](CONTRIBUTING.md) +## Standalone Installation -# INSTALLATION +Running `make install` will install Git Cola in your `$HOME` directory +(`$HOME/bin/git-cola`, `$HOME/share/git-cola`, etc). -Normally you can just do "make install" to install git-cola -in your `$HOME` directory (`$HOME/bin`, `$HOME/share`, etc). If you want to do a global install you can do make prefix=/usr install -The platform-specific installation methods below use the native -package manager. You should use one of these so that all of git-cola's -dependencies are installed. - Distutils is used by the `Makefile` via `setup.py` to install git-cola and its launcher scripts. distutils replaces the `#!/usr/bin/env python` lines in scripts with the full path to python at build time, which can be undesirable -when the runtime python is not the same as the build-time python. To disable -the replacement of the `#!/usr/bin/env python` lines, pass `USE_ENV_PYTHON=1` +when the runtime python is not the same as the build-time python. + +To disable the replacement of the `#!/usr/bin/env python` lines, pass `USE_ENV_PYTHON=1` to `make`. -## LINUX +## Linux Linux is it! Your distro has probably already packaged git-cola. If not, please file a bug against your distribution ;-) -### arch +### Arch Available in the [AUR](https://aur.archlinux.org/packages/git-cola/). -### debian, ubuntu +### Debian, Ubuntu apt install git-cola -### fedora +### Fedora dnf install git-cola -### gentoo +### Gentoo emerge git-cola -### opensuse, sle +### OpenSUSE, SLE zypper install git-cola -### slackware +### Slackware Available in [SlackBuilds.org](http://slackbuilds.org/result/?search=git-cola). -### 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 - -## Ubuntu +### Ubuntu [See here](https://packages.ubuntu.com/search?keywords=git-cola) for the versions that are available in Ubuntu's repositories. @@ -191,10 +159,19 @@ versions that are available in Ubuntu's repositories. There was a [PPA by @pavreh](https://launchpad.net/~pavreh/+archive/ubuntu/git-cola) but it has not been updated for a while. -## MAC OS X + +## 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 + +## macOS [Homebrew](https://brew.sh/) is the easiest way to install -git-cola's Qt4 and PyQt4 dependencies. We will use Homebrew to install +Git Cola's PyQt5 dependencies. We will use Homebrew to install the git-cola recipe, but build our own .app bundle from source. [Sphinx](http://sphinx-doc.org/latest/install.html) is used to build the @@ -203,34 +180,33 @@ documentation. brew install sphinx-doc brew install git-cola -Once brew has installed git-cola you can: +Once brew has installed `git-cola` you can: -1. Clone git-cola +1. Clone the git-cola repositroy - `git clone git://github.com/git-cola/git-cola.git && cd git-cola` + git clone https://github.com/git-cola/git-cola + cd git-cola 2. Build the git-cola.app application bundle - ``` make \ PYTHON=$(brew --prefix python3)/bin/python3 \ PYTHON_CONFIG=$(brew --prefix python3)/bin/python3-config \ SPHINXBUILD=$(brew --prefix sphinx-doc)/bin/sphinx-build \ git-cola.app - ``` 3. Copy it to /Applications - `rm -fr /Applications/git-cola.app && cp -r git-cola.app /Applications` + rsync -ar --delete git-cola.app/ /Applications/git-cola.app/ Newer versions of Homebrew install their own `python3` installation and provide the `PyQt5` modules for `python3` only. You have to use `python3 ./bin/git-cola` when running from the source tree. -### UPGRADING USING HOMEBREW +### Upgrading using Homebrew If you upgrade using `brew` then it is recommended that you re-install -git-cola's dependencies when upgrading. Re-installing ensures that the +Git Colaa's dependencies when upgrading. Re-installing ensures that the Python modules provided by Homebrew will be properly set up. A quick fix when upgrading to newer versions of XCode or macOS is to @@ -260,7 +236,7 @@ scratch using the instructions below should get things back in shape. # re-install git-cola and its dependencies brew install git-cola -## WINDOWS INSTALLATION +## Windows IMPORTANT If you have a 64-bit machine, install the 64-bit versions only. Do not mix 32-bit and 64-bit versions. @@ -273,30 +249,32 @@ Download and install the following: Once these are installed you can run Git Cola from the Start menu. -See "WINDOWS (continued)" below for more details. +See "Windows (Continued)" below for more details. -# GOODIES -git cola ships with an interactive rebase editor called `git-cola-sequence-editor`. +# Goodies + +Git Cola ships with an interactive rebase editor called `git-cola-sequence-editor`. `git-cola-sequence-editor` is used to reorder and choose commits when rebasing. Start an interactive rebase through the "Rebase" menu, or through the `git cola rebase` sub-command to use the `git-cola-sequence-editor`: - git cola rebase origin/main + git cola rebase @{upstream} -git-cola-sequence-editor can be launched independently of git cola by telling +`git-cola-sequence-editor` can be launched independently of git cola by telling `git rebase` to use it as its editor through the `GIT_SEQUENCE_EDITOR` environment variable: - env GIT_SEQUENCE_EDITOR="$PWD/bin/git-cola-sequence-editor" \ - git rebase -i origin/main + export GIT_SEQUENCE_EDITOR="$HOME/git-cola/bin/git-cola-sequence-editor" + git rebase -i @{upstream} + -# COMMAND-LINE TOOLS +# Git Cola Sub-commands -The git-cola command exposes various sub-commands that allow you to quickly +The `git-cola` command exposes various sub-commands that allow you to quickly launch tools that are available from within the git-cola interface. -For example, `./bin/git-cola find` launches the file finder, -and `./bin/git-cola grep` launches the grep tool. +For example, `git cola find` launches the file finder, +and `git cola grep` launches the grep tool. See `git cola --help-commands` for the full list of commands. @@ -334,7 +312,7 @@ See `git cola --help-commands` for the full list of commands. tag create tags version print the version -## HACKING +## Development The following commands should be run during development: @@ -359,32 +337,11 @@ Auto-format `po/*.po` files before committing when updating translations: When submitting patches, consult the [contributing guidelines](CONTRIBUTING.md). -## SOURCE INSTALL - -For Linux/Unix-like environments with symlinks, an easy way to use the latest -`git cola` is to keep a clone of the repository and symlink it into your -`~/bin` directory. If `$HOME/bin` is not already in your `$PATH` you can -add these two lines to the bottom of your `~/.bashrc` to make the linked -tools available. - - PATH="$HOME/bin":"$PATH" - export PATH - -Then, install git-cola by linking it into your `~/bin`: - - mkdir -p ~/src ~/bin - git clone git://github.com/git-cola/git-cola.git ~/src/git-cola - (cd ~/bin && - ln -s ../src/git-cola/bin/git-cola && - ln -s ../src/git-cola/bin/git-dag) - -You should then get the latest `git cola` in your shell. - -## PACKAGING NOTES +## Packaging Notes Git Cola installs its modules into the default Python site-packages directory -(eg. `lib/python2.7/site-packages`), and in its own private `share/git-cola/lib` +(eg. `lib/python3.7/site-packages`), and in its own private `share/git-cola/lib` area by default. The private modules are redundant and not needed when cola's modules have been installed into the site-packages directory. @@ -412,7 +369,7 @@ Python3 users on debian will need to install `python3-distutils` in order to run the Makefile's installation steps. `distutils` is a Python build requirement, but not needed at runtime. -# WINDOWS (continued) +# Windows (Continued) ## Development @@ -435,7 +392,7 @@ find python. For example: git config --global cola.pythonlocation /c/Python36 -## BUILDING WINDOWS INSTALLERS +## Building Windows Installers Windows installers are built using @@ -449,10 +406,10 @@ To build the installer using Pynsist run: This will generate an installer in `build/nsis/`. -## WINDOWS HISTORY BROWSER CONFIGURATION UPGRADE +## Windows "History Browser" Configuration Upgrade You may need to configure your history browser if you are upgrading from an -older version of Git Cola. +older version of Git Cola on Windows. `gitk` was originally the default history browser, but `gitk` cannot be launched as-is on Windows because `gitk` is a shell script. @@ -466,5 +423,5 @@ Preferences screen and change the history browser command to: "C:/Program Files/Git/bin/sh.exe" --login -i C:/Git/bin/gitk -git-dag became the default history browser on Windows in `v2.3`, so new -users should not need to configure anything. +`git-dag` became the default history browser on Windows in `v2.3`, so new +users do not need to configure anything. diff --git a/requirements/requirements.txt b/requirements/requirements.txt dissimilarity index 79% index 1a94d90f..692f127c 100644 --- a/requirements/requirements.txt +++ b/requirements/requirements.txt @@ -1,19 +1,9 @@ -# These packages are required to run git-cola. -# -# Additional functionality can be enabled by installing the packages -# in "requirements-optional.txt". - - -# qtpy provides a PyQt4/PyQt5/PySide2 abstraction layer. -# Git Cola ships with a vendored copy of "qtpy", but can also be made -# to use a distro-provided qtpy package. See README.md for more details. - -qtpy - - -# Git Cola can run with either PyQt5 or PySide2. You only need one of the two. -# Install one of the following packages. Git Cola is authored using PyQt5, -# but PySide2 (and even PyQt4) is also supported and should work in practice. - -# PyQt5; python_version>='3.0' # recommended -# PySide2 +# These packages are required to run git-cola. +# +# Git Cola can run with either PyQt5 or PySide2. You only need one of the two. +# We recommend PyQt5 but PySide2 is also supported and can be used instead. +PyQt5 + +# qtpy provides a PyQt5/PyQt6/PySide2 abstraction layer that makes it possible +# to choose between PyQt5, PySide2 and other Qt backends at runtime. +qtpy -- 2.11.4.GIT