python-swiftclient

Lack of detail on "swift" command

Bug #1269715 reported by Chris Stratford
10
This bug affects 1 person
Affects Status Importance Assigned to Milestone
python-swiftclient
In Progress
Undecided
Christian Schwede

Bug Description

The command-line swift command has no man page, making it hard to tell what the command will and will not do ("swift --help" provides some information, but not enough)

As a specific example, a file that has been "swift upload"-ed gains an md5sum in the etag, but there is no documentation to say whether the upload is verified against this or whether it is up to the user to check it matches afterwards.

Likewise, there is no docmentation of return codes. A successful upload appears to return 0, as expected and I'm assuming a failure returns something else (what?) Are there different return codes defending on the type of error (e.g. authentication failure returns 1, md5sum mismatch returns 2, etc.)?

Revision history for this message
Christian Schwede (cschwede) wrote :

There is already a manpage for python-swiftclient: https://github.com/openstack/python-swiftclient/blob/master/doc/manpages/swift.1

It is not very detailed yet, I'll update it with more informations.

Changed in swift:
assignee: nobody → Christian Schwede (cschwede)
Christian Schwede (cschwede)
affects: swift → python-swiftclient
Chmouel Boudjnah (chmouel)
Changed in python-swiftclient:
status: New → Triaged
Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to python-swiftclient (master)

Reviewed: https://review.openstack.org/67106
Committed: https://git.openstack.org/cgit/openstack/python-swiftclient/commit/?id=63c9917085ac4d5c99afc61e5865cb88417dcd27
Submitter: Jenkins
Branch: master

commit 63c9917085ac4d5c99afc61e5865cb88417dcd27
Author: Christian Schwede <email address hidden>
Date: Thu Jan 16 10:23:02 2014 +0000

    Install swiftclient manpage

    Currently the existing manpage isn't copied to /usr/local/man/man1
    when installing swiftclient from source. This patch fixes this.

    Change-Id: Ib2ee091d5e1d4c37a4e5a00f50fa19df44bd3c41
    Partial-Bug: 1269715

Revision history for this message
Dirk Mueller (dmllr) wrote :

this is a bit problematic if you want to install swiftclient on non-ubuntu setup though, as man pages are in share/man/* there. I'm not sure why this was special-cased for one man page for one client.. at the moment the only solution I see is to revert this patch :/

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix proposed to python-swiftclient (master)

Fix proposed to branch: master
Review: https://review.openstack.org/67813

Changed in python-swiftclient:
status: Triaged → In Progress
Revision history for this message
Christian Schwede (cschwede) wrote :

@Dirk: thanks for the note, I uploaded a new patch fixing this.

My intention was to follow the FHS, and from the spec /usr/local/man should be the correct place for files in /usr/local/bin:

"Manual pages for commands and data under /usr/local are stored in /usr/local/man."

http://www.pathname.com/fhs/pub/fhs-2.3.html#USRSHAREMANMANUALPAGES

Obviously this works not for some distros, thus I changed the prefix to share/man/man1.

Revision history for this message
OpenStack Infra (hudson-openstack) wrote : Fix merged to python-swiftclient (master)

Reviewed: https://review.openstack.org/67813
Committed: https://git.openstack.org/cgit/openstack/python-swiftclient/commit/?id=65d7a136f69a2f0a692eeaed7ca68e2a5f91b07d
Submitter: Jenkins
Branch: master

commit 65d7a136f69a2f0a692eeaed7ca68e2a5f91b07d
Author: Christian Schwede <email address hidden>
Date: Mon Jan 20 10:55:20 2014 +0000

    Install manpage in share/man/man1 instead of man/man1

    According to FHS 2.3 the correct place to install the manpage for a
    binary in /usr/local/bin/ would be /usr/local/man/.

    However, on Debian/Ubuntu-based systems /usr/local/man/ is a link to
    /usr/local/share/man/ and on other systems /usr/local/man/ might not
    exist at all.

    Even worse, if the client is installed in /usr/bin/ the manpage
    should should be installed in /usr/share/man, but will be installed
    in /usr/man/ which is completely wrong.

    This patch fixes this and uses share/man/man1 as common prefix. Doing
    this will install the manpage either in /usr/local/share/man/man1 or
    /usr/share/man/man1.

    Partial-Bug: 1269715
    Change-Id: I590932f00476eacd434cdae012fd62010845581d

To post a comment you must log in.
This report contains Public information  
Everyone can see this information.
Subscribing...

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.