cartman
=======
.. image:: https://travis-ci.org/tamentis/cartman.png
*cartman* allows you to create and manage your Trac_ tickets from the
command-line, without the need to setup physical access to the Trac_
installation/database or even the need to install a plugin on Trac_. All you
need is a Trac_ account.
Examples
--------
Create a new ticket, that will open your $EDITOR::
$ cm new
View the content of a ticket::
$ cm view 1514
Configuration
-------------
At a minimum you need to create a ``~/.cartman/config`` file with the
following::
[trac]
base_url = http://your.trac.install/
username = tamentis
password = sitnemat
The password can also be specified through a `TRAC_PASSWORD`
environment variable, which overrides the above `password` field.
Configuration Options
^^^^^^^^^^^^^^^^^^^^^
Each section represent a site which can be selected using the ``-s``
command-line argument. Within each section, the following settings are
available:
- ``base_url`` - required, defines the URL of your Trac system
- ``auth_type`` - forces an authentication type, currently available: ``basic``
(default), ``digest``, ``acctmgr`` or ``none``.
- ``username`` - required if ``auth_type`` is not ``none``
- ``password`` - required if ``auth_type`` is not ``none``
- ``verify_ssl_cert`` - ignore self-signed or invalid SSL certificates if set
to false.
- ``editor`` - override the editor defined the ``$EDITOR`` environment
variable.
Command walk through
--------------------
Report Listing and Search
^^^^^^^^^^^^^^^^^^^^^^^^^
Dump a list of tickets on screen, without details::
$ cm report 1
#142. fix world hunger (bjanin@)
#159. ignore unpaid rent (bjanin@)
Another way to find ticket is using the search command::
$ cm search dead mouse
#154. mickey
Ticket View
^^^^^^^^^^^
Show all the properties of a ticket::
$ cm view 1
List of Reports
^^^^^^^^^^^^^^^
Get a list of all the available reports with::
$ cm reports
System Properties
^^^^^^^^^^^^^^^^^
This will dump on screen all the Milestones, Components, Versions::
$ cm properties
Creating a ticket
^^^^^^^^^^^^^^^^^
Creating a ticket will work similarly to writing a new email in mutt_, it loads
your current ``$EDITOR`` and lets you edit the details of the ticket. Assuming
all the parameters are correct, it will create the ticket as soon as you save
and exit and return the ticket number. If your ticket does not appear valid
(missing required field, inexistent Milestone, etc.) *cartman* will stop and
lists each error and let you return to your editor::
$ cm new
-- opens your editor --
Found the following errors:
- Invalid 'Subject': cannot be blank
- Invalid 'Milestone': expected: Bug Bucket, Release 2, Release 3
-- Hit Enter to return to editor, ^C to abort --
The first parameter to ``cm`` is the owner of the ticket, it populates the
``To`` field by default::
$ cm new jcarmack
If your Trac has custom fields, you can use their identifier in the headers,
e.g.::
story_id: 5123
iteration: 15
If you specify a template with -t, cartman will look for a matching file in the
``~/.cartman/templates`` folder and will use it as a base for your ticket::
$ cm new -t sysadmin
You can define a ``default`` template in this same directory in order to set
the template used by default (without ``-t``).
Commenting on a ticket
^^^^^^^^^^^^^^^^^^^^^^
Just like creating a ticket, adding a comment is just like mutt_, your current
``$EDITOR`` will be loaded on a blank file for you to edit. Upon save and exit,
*cartman* will commit this new comment and return silently, unless an error
occurs::
$ cm comment 1
If the comment is short enough to fit on the command line, you may use the
``-m`` flag as such::
$ cm comment 1 -m "you forgot to call twiddle()"
View/Set the status of a ticket
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
View the current status of a ticket, and the available statuses::
$ cm status 1
Set a ticket as accepted::
$ cm status 1 accept
If you need to add a comment with this status change, you can use the ``-c``
flag, it will open your default editor::
$ cm status 1 reopen -c
You may also use the ``-m`` flag to define the comment in-line, without the use
of an editor::
$ cm status 1 reopen -m "does not work with x = y"
Advanced configuration
----------------------
If you are using vim_ as your default editor, you also might want to add
email-like syntax highlighting to match the ``.cm.ticket`` extension::
autocmd BufNewFile *.cm.ticket setf mail
If you use multiple Trac sites, you can have multiple configurations in the
same file using the section to separate the sites, here is an example::
[other]
base_url = http://other.trac.site/
username = tamentis
password = sitnemat
verify_ssl_cert = False
You would pass the ``-s`` parameter to ``cm`` to define which site to access::
cm -s other report 1
You may define all common configuration settings in the ``[DEFAULT]`` section.
Using cartman without editor
----------------------------
You may need to integrate cartman with other software where opening an editor
does not make sense. In that case you can automatically create tickets from
a file using the ``--message-file`` option::
cm new --message-file=secerror.txt
This file would need to contain a complete ticket, if anything is missing,
cartman will exit with an error message.
Installation
------------
Quick and dirty if you are not familiar with Python packaging::
sudo python setup.py install
Requirements
------------
- Python 2.7+, 3.3+ (not 3.2, not 2.6)
- python-requests 1.2 and above
Compatibility
-------------
- Tested on Trac 0.12.5 and 1.2.x
- Probably still works on 0.11, but untested.
Hacking
-------
- The following command will create one virtualenv and sandbox for each latest
0.12, 1.0 and 1.2 releases of Trac::
$ ./tools/mkenv.sh
- You can then serve one or the other using, the default admin user/pass is
sandbox/sandbox::
$ ./tools/serve-0.12.sh
$ ./tools/serve-1.0.sh
$ ./tools/serve-1.2.sh
- Follow PEP-8, existing style then the following notes.
- For dictionaries, lists: keep commas after each items, closing bracket
should close on the same column as the first letter of the statement with the
opening bracket.
- Use double-quotes for strings unless it makes it easier on certain strings
(avoids escaped double-quotes).
- If an error is exceptional, let the exception rise.
Distribute
----------
- Change the version in cartman/__init__.py, update CHANGES.txt
- Commit
- Create a tag::
git tag -a vX.Y.Z -m 'Releasing vX.Y.Z'
git push --tags
- Download the file from github (release section),
- Sign it::
gpg --armor --detach-sig cartman-X.Y.Z.tar.gz
- Distribute on Pypi::
python setup.py sdist upload
.. _Trac: http://trac.edgewall.org/
.. _vim: http://www.vim.org/
.. _mutt: http://www.mutt.org/
Raw data
{
"_id": null,
"home_page": "http://tamentis.com/projects/cartman/",
"name": "cartman",
"maintainer": "",
"docs_url": null,
"requires_python": ">2.7,>=3.3",
"maintainer_email": "",
"keywords": "",
"author": "Bertrand Janin",
"author_email": "Bertrand Janin <bertrand@janin.com>",
"download_url": "https://files.pythonhosted.org/packages/bd/74/7819f1dfab404094f6d18001ad692fe16fc109017c556dcbb424173b556f/cartman-0.3.1.tar.gz",
"platform": null,
"description": "cartman\n=======\n\n.. image:: https://travis-ci.org/tamentis/cartman.png\n\n*cartman* allows you to create and manage your Trac_ tickets from the\ncommand-line, without the need to setup physical access to the Trac_\ninstallation/database or even the need to install a plugin on Trac_. All you\nneed is a Trac_ account.\n\nExamples\n--------\nCreate a new ticket, that will open your $EDITOR::\n\n $ cm new\n\nView the content of a ticket::\n\n $ cm view 1514\n\nConfiguration\n-------------\nAt a minimum you need to create a ``~/.cartman/config`` file with the\nfollowing::\n\n [trac]\n base_url = http://your.trac.install/\n username = tamentis\n password = sitnemat\n\nThe password can also be specified through a `TRAC_PASSWORD`\nenvironment variable, which overrides the above `password` field.\n\nConfiguration Options\n^^^^^^^^^^^^^^^^^^^^^\nEach section represent a site which can be selected using the ``-s``\ncommand-line argument. Within each section, the following settings are\navailable:\n\n- ``base_url`` - required, defines the URL of your Trac system\n- ``auth_type`` - forces an authentication type, currently available: ``basic``\n (default), ``digest``, ``acctmgr`` or ``none``.\n- ``username`` - required if ``auth_type`` is not ``none``\n- ``password`` - required if ``auth_type`` is not ``none``\n- ``verify_ssl_cert`` - ignore self-signed or invalid SSL certificates if set\n to false.\n- ``editor`` - override the editor defined the ``$EDITOR`` environment\n variable.\n\n\nCommand walk through\n--------------------\n\nReport Listing and Search\n^^^^^^^^^^^^^^^^^^^^^^^^^\nDump a list of tickets on screen, without details::\n\n $ cm report 1\n #142. fix world hunger (bjanin@)\n #159. ignore unpaid rent (bjanin@)\n\nAnother way to find ticket is using the search command::\n\n $ cm search dead mouse\n #154. mickey\n\nTicket View\n^^^^^^^^^^^\nShow all the properties of a ticket::\n\n $ cm view 1\n\nList of Reports\n^^^^^^^^^^^^^^^\nGet a list of all the available reports with::\n\n $ cm reports\n\nSystem Properties\n^^^^^^^^^^^^^^^^^\nThis will dump on screen all the Milestones, Components, Versions::\n\n $ cm properties\n\nCreating a ticket\n^^^^^^^^^^^^^^^^^\nCreating a ticket will work similarly to writing a new email in mutt_, it loads\nyour current ``$EDITOR`` and lets you edit the details of the ticket. Assuming\nall the parameters are correct, it will create the ticket as soon as you save\nand exit and return the ticket number. If your ticket does not appear valid\n(missing required field, inexistent Milestone, etc.) *cartman* will stop and\nlists each error and let you return to your editor::\n\n $ cm new\n -- opens your editor --\n\n Found the following errors:\n - Invalid 'Subject': cannot be blank\n - Invalid 'Milestone': expected: Bug Bucket, Release 2, Release 3\n\n -- Hit Enter to return to editor, ^C to abort --\n\nThe first parameter to ``cm`` is the owner of the ticket, it populates the\n``To`` field by default::\n\n $ cm new jcarmack\n\nIf your Trac has custom fields, you can use their identifier in the headers,\ne.g.::\n\n story_id: 5123\n iteration: 15\n\nIf you specify a template with -t, cartman will look for a matching file in the\n``~/.cartman/templates`` folder and will use it as a base for your ticket::\n\n $ cm new -t sysadmin\n\nYou can define a ``default`` template in this same directory in order to set\nthe template used by default (without ``-t``).\n\nCommenting on a ticket\n^^^^^^^^^^^^^^^^^^^^^^\nJust like creating a ticket, adding a comment is just like mutt_, your current\n``$EDITOR`` will be loaded on a blank file for you to edit. Upon save and exit,\n*cartman* will commit this new comment and return silently, unless an error\noccurs::\n\n $ cm comment 1\n\nIf the comment is short enough to fit on the command line, you may use the\n``-m`` flag as such::\n\n $ cm comment 1 -m \"you forgot to call twiddle()\"\n\nView/Set the status of a ticket\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\nView the current status of a ticket, and the available statuses::\n\n $ cm status 1\n\nSet a ticket as accepted::\n\n $ cm status 1 accept\n\nIf you need to add a comment with this status change, you can use the ``-c``\nflag, it will open your default editor::\n\n $ cm status 1 reopen -c\n\nYou may also use the ``-m`` flag to define the comment in-line, without the use\nof an editor::\n\n $ cm status 1 reopen -m \"does not work with x = y\"\n\nAdvanced configuration\n----------------------\nIf you are using vim_ as your default editor, you also might want to add\nemail-like syntax highlighting to match the ``.cm.ticket`` extension::\n\n autocmd BufNewFile *.cm.ticket setf mail\n\nIf you use multiple Trac sites, you can have multiple configurations in the\nsame file using the section to separate the sites, here is an example::\n\n [other]\n base_url = http://other.trac.site/\n username = tamentis\n password = sitnemat\n verify_ssl_cert = False\n\n\nYou would pass the ``-s`` parameter to ``cm`` to define which site to access::\n\n cm -s other report 1\n\nYou may define all common configuration settings in the ``[DEFAULT]`` section.\n\nUsing cartman without editor\n----------------------------\nYou may need to integrate cartman with other software where opening an editor\ndoes not make sense. In that case you can automatically create tickets from\na file using the ``--message-file`` option::\n\n cm new --message-file=secerror.txt\n\nThis file would need to contain a complete ticket, if anything is missing,\ncartman will exit with an error message.\n\nInstallation\n------------\nQuick and dirty if you are not familiar with Python packaging::\n\n sudo python setup.py install\n\nRequirements\n------------\n- Python 2.7+, 3.3+ (not 3.2, not 2.6)\n- python-requests 1.2 and above\n\n\nCompatibility\n-------------\n- Tested on Trac 0.12.5 and 1.2.x\n- Probably still works on 0.11, but untested.\n\n\nHacking\n-------\n- The following command will create one virtualenv and sandbox for each latest\n 0.12, 1.0 and 1.2 releases of Trac::\n\n $ ./tools/mkenv.sh\n\n- You can then serve one or the other using, the default admin user/pass is\n sandbox/sandbox::\n\n $ ./tools/serve-0.12.sh\n $ ./tools/serve-1.0.sh\n $ ./tools/serve-1.2.sh\n\n- Follow PEP-8, existing style then the following notes.\n- For dictionaries, lists: keep commas after each items, closing bracket\n should close on the same column as the first letter of the statement with the\n opening bracket.\n- Use double-quotes for strings unless it makes it easier on certain strings\n (avoids escaped double-quotes).\n- If an error is exceptional, let the exception rise.\n\n\nDistribute\n----------\n- Change the version in cartman/__init__.py, update CHANGES.txt\n- Commit\n- Create a tag::\n\n git tag -a vX.Y.Z -m 'Releasing vX.Y.Z'\n git push --tags\n\n- Download the file from github (release section),\n- Sign it::\n\n gpg --armor --detach-sig cartman-X.Y.Z.tar.gz\n\n- Distribute on Pypi::\n\n python setup.py sdist upload\n\n\n.. _Trac: http://trac.edgewall.org/\n.. _vim: http://www.vim.org/\n.. _mutt: http://www.mutt.org/\n",
"bugtrack_url": null,
"license": "ISC License (ISCL, BSD/MIT compatible)",
"summary": "trac command-line tools",
"version": "0.3.1",
"project_urls": {
"Bug Tracker": "https://github.com/tamentis/cartman/issues",
"Homepage": "https://tamentis.com/projects/cartman/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d04e9774185ede33e6d60930f33c29c1c05aa94e956a911ebc5508708aa2a097",
"md5": "3ccc9043ef7173d109fdfa6db74cf000",
"sha256": "e692386fea2b4e8556e5d8f61d427c1c2ef5b8c70c2a864cb1426dadef6b86d4"
},
"downloads": -1,
"filename": "cartman-0.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3ccc9043ef7173d109fdfa6db74cf000",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">2.7,>=3.3",
"size": 21910,
"upload_time": "2023-05-05T17:11:44",
"upload_time_iso_8601": "2023-05-05T17:11:44.209415Z",
"url": "https://files.pythonhosted.org/packages/d0/4e/9774185ede33e6d60930f33c29c1c05aa94e956a911ebc5508708aa2a097/cartman-0.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bd747819f1dfab404094f6d18001ad692fe16fc109017c556dcbb424173b556f",
"md5": "446fe3017172aebcdf2297c4c54c78a6",
"sha256": "a4d9a5f1ec5c116a5bc47a25dd4cff121ffa74a34927029cd69302fa4191b6d8"
},
"downloads": -1,
"filename": "cartman-0.3.1.tar.gz",
"has_sig": false,
"md5_digest": "446fe3017172aebcdf2297c4c54c78a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">2.7,>=3.3",
"size": 23458,
"upload_time": "2023-05-05T17:11:48",
"upload_time_iso_8601": "2023-05-05T17:11:48.087903Z",
"url": "https://files.pythonhosted.org/packages/bd/74/7819f1dfab404094f6d18001ad692fe16fc109017c556dcbb424173b556f/cartman-0.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-05 17:11:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tamentis",
"github_project": "cartman",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "cartman"
}
JSON
