1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
======
git-pw
======
.. NOTE: If editing this, be sure to update the line numbers in 'doc/index'
.. image:: https://badge.fury.io/py/git-pw.svg
:target: https://badge.fury.io/py/git-pw
:alt: PyPi Status
.. image:: https://readthedocs.org/projects/git-pw/badge/?version=latest
:target: http://git-pw.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://github.com/getpatchwork/git-pw/actions/workflows/ci.yaml/badge.svg
:target: https://github.com/getpatchwork/git-pw/actions/workflows/ci.yaml
:alt: Build Status
*git-pw* is a tool for integrating Git with `Patchwork`__, the web-based patch
tracking system.
.. important::
`git-pw` only supports Patchwork 2.0+ and REST API support must be enabled
on the server end. You can check for support by browsing ``/about`` for your
given instance. If this page returns a 404, you are using Patchwork < 2.0.
The `pwclient`__ utility can be used to interact with older Patchwork
instances or instances with the REST API disabled.
.. __: http://jk.ozlabs.org/projects/patchwork/
.. __: https://patchwork.ozlabs.org/help/pwclient/
Installation
------------
The easiest way to install *git-pw* and its dependencies is using ``pip``. To
do so, run:
.. code-block:: bash
$ pip install git-pw
You can also install *git-pw* manually. First, install the required
dependencies. On Fedora, run:
.. code-block:: bash
$ sudo dnf install python3-requests python3-click python3-pbr \
python3-arrow python3-tabulate python3-yaml
On Ubuntu, run:
.. code-block:: bash
$ sudo apt-get install python3-requests python3-click python3-pbr \
python3-arrow python3-tabulate python3-yaml
Once dependencies are installed, clone this repo and install with ``pip``:
.. code-block:: bash
$ git clone https://github.com/getpatchwork/git-pw
$ cd git-pw
$ pip install --user .
Getting Started
---------------
To begin, you'll need to configure Git settings appropriately. The following
settings are **required**:
``pw.server``
The URL for the Patchwork instance's API. This should include the API
version::
https://patchwork.ozlabs.org/api/1.3
You can discover the API version supported by your instance by comparing the
server version, found at ``/about``, with the API versions provided in the
`documentation`__. For example, if your server is running Patchwork version
3.2.x, you should use API version 1.3.
.. __: https://patchwork.readthedocs.io/en/stable-3.2/api/rest/#rest-api-versions
``pw.project``
The project name or list-id. This will appear in the URL when using the web
UI::
https://patchwork.ozlabs.org/project/{project_name}/list/
For read-write access, you also need authentication - you can use either API
tokens or a username/password combination:
``pw.token``
The API token for your Patchwork account.
``pw.username``
The username for your Patchwork account.
``pw.password``
The password for your Patchwork account.
If only read-only access is desired, credentials can be omitted.
The following settings are **optional** and may need to be set depending on
your Patchwork instance's configuration:
``pw.states``
The states that can be applied to a patch using the ``git pw patch update``
command. Should be provided in slug form (``changes-requested`` instead of
``Changes Requested``). Only required if your Patchwork instance uses
non-default states.
You can set these settings using the ``git config`` command. This should be
done in the repo in which you intend to apply patches. For example, to
configure the Patchwork project, run:
.. code-block:: bash
$ git config pw.server 'https://patchwork.ozlabs.org/api/1.1/'
$ git config pw.project 'patchwork'
Development
-----------
If you're interested in contributing to *git-pw*, first clone the repo:
.. code-block:: bash
$ git clone https://github.com/getpatchwork/git-pw
$ cd git-pw
Create a *virtualenv*, then install the package in `editable`__ mode:
.. code-block:: bash
$ virtualenv .venv
$ source .venv/bin/activate
$ pip install --editable .
.. __: https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs
Documentation
-------------
Documentation is available on `Read the Docs`__
.. __: https://git-pw.readthedocs.org/
|
