From f9279cda32c207c7aed4c235608e60e69731acde Mon Sep 17 00:00:00 2001 From: Dirk Avery Date: Wed, 27 May 2020 14:52:52 -0400 Subject: [PATCH] Bump version, update docs --- README.md | 27 +++++++++++++++++++-------- oschmod/cli.py | 3 ++- 2 files changed, 21 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index ba492b3..f454cdc 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,9 @@ ## oschmod TL;DR -macOS and other Linux-based operating systems include a tool called `chmod`. ***oschmod*** provides consistent `chmod`-like functionality that works on **Windows**, macOS, and Linux! +***oschmod*** brings `chmod` functionality to **Windows**, macOS, and Linux! If you're not familiar, `chmod` is a handy macOS and Linux-only tool for setting file permissions. -Prior to ***oschmod***, Windows file permissions couldn't be set in the familiar `chmod` way. Tools did not translate `chmod`-style permissions into Windows-style file permissions. Even though Python's `os.chmod()` sets read, write, and execute file permissions, on Windows, `os.chmod()` basically has no effect. Even worse, Python on Windows gives no warnings or errors. If you think you've protected a file on Windows with `os.chmod()`, you have not. +Prior to ***oschmod***, Windows file permissions couldn't be set in the familiar `chmod` way. Tools did not translate `chmod`-style permissions into Windows-style file permissions. Even though Python's `os.chmod()` sets read, write, and execute file permissions, on Windows, `os.chmod()` basically has no effect. Even worse, Python on Windows gives no warnings or errors. If you think you set file permissions on Windows with `os.chmod()`, you're wrong! ***oschmod*** allows you to set consistent file permissions in a consistent way across platforms. @@ -31,9 +31,19 @@ Prior to ***oschmod***, Windows file permissions couldn't be set in the familiar $ pip install oschmod ``` +## GNU Documentation + +***oschmod*** changes the file mode bits of each given file according to mode, which can be either a symbolic representation of changes to make, or an octal number representing the bit pattern for the new mode bits. + +The format of a symbolic mode is `[ugoa...][+-=][perms...]` where perms is zero or more letters from the set `rwx`. Multiple symbolic modes can be given, separated by commas. + +A combination of the letters `ugoa` controls which users' access to the file will be changed: the user who owns it (`u`), other users in the file's group (`g`), other users not in the file's group (`o`), or all users (`a`). If none of these are given, the effect is as if `a` were given. + +*(Modified from the GNU manpage for chmod.)* + ## Command line interface -***oschmod*** brings the ability to set consistent file permissions using the command line to Windows, macOS, and Linux platforms. If you are familiar with `chmod` on Unix, Linux and/or macOS, ***oschmod*** works similarly, albeit with fewer options. +***oschmod*** brings the ability to set consistent file permissions using the command line to Windows, macOS, and Linux platforms. If you are familiar with `chmod`, ***oschmod*** works similarly, albeit with fewer options. ```console $ oschmod -h @@ -57,9 +67,10 @@ You can use symbolic (e.g., "u+rw") or octal (e.g., "600) representations of mod ### Symbolic representation examples Symbolic representation mode modifiers have three parts: - 1. **whom:** To whom does the modification apply? You can include zero or more of `[ugoa]*` where `a` is for all, `u` is for the file owner (i.e., "**u**ser"), `g` is for the file group, and `o` is for others. In other words, `ugo` is equivalent to `a`. Also, if you do not provide a "whom," ***oschmod*** assumes you mean `a` (everyone). - 2. **operation:** Which operation should be applied? You must include one and only one operation, `[+-=]{1}`, per modifier (although you can have multiple modifiers). `+` adds permissions, `-` removes permissions, and `=` sets permissions regardless of previous permissions. `+` and `-` modifications often depend on the current permissions. - 3. **permission:** Which permission or permissions will be affected? You can include zero or more of `[rwx]*` where `r` is for read, `w` is for write, and `x` is for execute. If you do not include a permission with `+` or `-` (e.g., `u-`), the modifier has no effect. However, if you use no permissions with `=` (e.g., `o=`), all permissions are removed. + +1. **whom:** To whom does the modification apply? You can include zero or more of `[ugoa]*` where `a` is for all, `u` is for the file owner (i.e., "**u**ser"), `g` is for the file group, and `o` is for others. In other words, `ugo` is equivalent to `a`. Also, if you do not provide a "whom," ***oschmod*** assumes you mean `a` (everyone). +2. **operation:** Which operation should be applied? You must include one and only one operation, `[+-=]{1}`, per modifier (although you can have multiple modifiers). `+` adds permissions, `-` removes permissions, and `=` sets permissions regardless of previous permissions. `+` and `-` modifications often depend on the current permissions. +3. **permission:** Which permission or permissions will be affected? You can include zero or more of `[rwx]*` where `r` is for read, `w` is for write, and `x` is for execute. If you do not include a permission with `+` or `-` (e.g., `u-`), the modifier has no effect. However, if you use no permissions with `=` (e.g., `o=`), all permissions are removed. **Example 1:** To give everyone execute permissions on a file (all of these are equivalent): @@ -106,14 +117,14 @@ $ oschmod 700 ## Python usage -You can use ***oschmod*** from Python code. Any of the command line examples above will work very similarly. For example, "Example 4" above, in Python code, would look like this: +You can use ***oschmod*** from Python code. Any of the command line examples above will work very similarly. For example, *Example 4* above, in Python code, would look like this: ```python import oschmod oschmod.set_mode("myfile", "a+rwx,g-w,o-x") ``` -"Example 5" above, in Python code, could be done in two ways: +*Example 5* above, in Python code, could be done in two ways: ```python import oschmod diff --git a/oschmod/cli.py b/oschmod/cli.py index 04ce033..d36fb03 100644 --- a/oschmod/cli.py +++ b/oschmod/cli.py @@ -14,7 +14,8 @@ def main(): description='Change the mode (permissions) of a file or directory') parser.add_argument('-R', action='store_true', help='apply mode recursively') - parser.add_argument('mode', nargs=1, help='octal or symbolic mode of the object') + parser.add_argument( + 'mode', nargs=1, help='octal or symbolic mode of the object') parser.add_argument('object', nargs=1, help='file or directory') args = parser.parse_args()