|
1 | | -# blame-tracker |
| 1 | +# blame-tracker.py |
2 | 2 | Accuse guilty developers with blame-tracker! |
| 3 | + |
| 4 | + |
| 5 | + |
| 6 | +## Usage |
| 7 | + |
| 8 | +Blame-tracker has several flags, but there are only a few you need to know about: |
| 9 | + |
| 10 | +### Important Flags |
| 11 | + |
| 12 | +|Short|Long|Args|Description| |
| 13 | +|-|-|-|-| |
| 14 | +|`-i`|`--info`|❌|Print info messages about the statistics related to the commits.| |
| 15 | +|`-d`|`--days-ago`|`int`|Set or shift the start date for the collection of commits back by a number of days.| |
| 16 | +|`-t0`|`--since`|An American formatted date like `1/31/1970` (January 31st, 1970), or an [ISO 8601 formatted date](https://en.wikipedia.org/wiki/ISO_8601).|Set the start date for the collection of commits.| |
| 17 | +|`-t1`|`--until`|👆|Set the end date for the collection of commits.| |
| 18 | +|`-in`|`--include`|One or more more [file patterns](https://en.wikipedia.org/wiki/Glob_(programming)).|Include one or more patterns of files. To include all C files in a given folder, you could do `-in "folder/*.c"` (or `"folder/**/*.c"` for recursion)| |
| 19 | +|`-ex`|`--exclude`|👆|Exclude one or more patterns of files. You can do this on your build folders `-ex build`, or all markdown files `-ex "**/*.md"`| |
| 20 | +|`-by`|`--author`|One or more authors' names.|This will filter the annotated output to only show code by the authors supplied.| |
| 21 | +|`-o`|`--output`|The output path for the accused lines of code.|This flag is optional. This writes the relevant, annotated code to the output file according to the filters provided in the arguments.| |
| 22 | + |
| 23 | +### Less Important Flags |
| 24 | + |
| 25 | +These are flags that you probably won't need to use, but they're here if you need them. |
| 26 | + |
| 27 | +|Short|Long|Args|Description| |
| 28 | +|-|-|-|-| |
| 29 | +|`-f`|`--format`|A format string to print the accused code with.|The format arguments used are `file_path` (the path of the accused file), `author` (the author of the file), `content` (the line in the accusation), `date` (the date of the commit), and `time` (the time of the commit). The default format specifier is `"{name:12} ({author} on {date} at {time}): {content}"`| |
| 30 | +|`-w`|`--weeks-ago`|`int`|Set or shift the start date for the collection of commits back by a number of weeks.| |
| 31 | +|`-dir`|`--directory`|A path to a Git repository.|Set the directory of the git repository to accuse. By default this is just the current directory.| |
| 32 | +|`-ws`|`--keep-whitespace`|❌|Use this flag to keep whitespace lines in the output file.| |
| 33 | +|`-s`|`--silence-warnings`|❌|Use this flag to silence warnings. This will allow bytes-like data to be accused and included in the output file silently. Don't use this if you don't wanna include massive binary files (which you probably don't).| |
| 34 | +|`-v`|`--verbose`|`1`, `2`, or `3`|Set the verbosity level for printing out runtime information. `1` is the same as enabling `--info`.| |
| 35 | +|`-h`|`--help`|❌|Print the help message.| |
| 36 | + |
| 37 | +### Examples |
| 38 | + |
| 39 | +```bash |
| 40 | +# Print the blame for all C files (recursively) in the current repository. |
| 41 | +blame-tracker.py -in "**/*.c" |
| 42 | +# Print the blame for all C files (recursively) in another given repository |
| 43 | +blame-tracker.py -r /path/to/repo -in "**/*.c" |
| 44 | +# Print the blame for all C files in a `src` repository and exclude all markdown files in the current directory |
| 45 | +blame-tracker.py -in "src/*.c" -ex "*.md" |
| 46 | +# Print the blame for a specific author in the current directory |
| 47 | +blame-tracker.py -by "Adam McDaniel" |
| 48 | +# Print the blame for a specific author in the current directory and include all rust files (recursively), excluding all files in the `target` directory |
| 49 | +blame-tracker.py -by "Adam McDaniel" -in "**/*.rs" -ex "target" |
| 50 | +# Print a formatted blame for a specific author in the current directory and include all rust files (recursively), excluding all files in the `target` directory |
| 51 | +blame-tracker.py -by "Adam McDaniel" -in "**/*.rs" -ex "target" -f "{name:12} {date} ({author}) {content}" |
| 52 | +# Get the blame for a specific author in the current directory and include all rust files (recursively), excluding all files in the `target` directory, and write it the output to a file |
| 53 | +blame-tracker.py -by "Adam McDaniel" -in "**/*.rs" -ex "target" -o output.txt |
| 54 | +``` |
| 55 | + |
| 56 | +## Installation |
| 57 | + |
| 58 | +Requirements: |
| 59 | +- Python 3.11 |
| 60 | +- Git |
| 61 | + |
| 62 | +### As a Script |
| 63 | + |
| 64 | +You can run `blame-tracker.py` as a script by running `python3 blame-tracker.py` in the directory of the repository you want to blame. You can also make it an executable with `chmod +x blame-tracker.py` and run it with `./blame-tracker.py`. You can also add the directory of the repository to your `PATH` environment variable to run it from anywhere. This is the easiest way to use `blame-tracker.py`, and is possible on all platforms (but on Windows it's a bit more tedious). |
| 65 | + |
| 66 | +```bash |
| 67 | +## Download the script with git |
| 68 | +git clone https://github.com/adam-mcdaniel/blame-tracker |
| 69 | +cp blame-tracker/blame-tracker.py . |
| 70 | +rm -rf blame-tracker |
| 71 | +## Download the script with curl |
| 72 | +curl -O https://raw.githubusercontent.com/adam-mcdaniel/blame-tracker/main/blame-tracker.py |
| 73 | + |
| 74 | +## Make the script executable (optional) |
| 75 | +chmod +x blame-tracker.py |
| 76 | + |
| 77 | +## Run the script |
| 78 | +python3 blame-tracker.py -h |
| 79 | +# or |
| 80 | +./blame-tracker.py -h |
| 81 | +``` |
| 82 | + |
| 83 | +### \*nix Installation |
| 84 | + |
| 85 | +You can install `blame-tracker.py` on Linux very simply by saving it to your `~/.local/bin` directory. You can do this by cloning the repository and copying the file over, or by using `curl` to download the file directly. |
| 86 | + |
| 87 | +#### Through Git |
| 88 | + |
| 89 | +```bash |
| 90 | +git clone https://github.com/adam-mcdaniel/blame-tracker |
| 91 | +cd blame-tracker |
| 92 | +chmod +x blame-tracker.py |
| 93 | +# If this directory doesn't exist, you can create it with `mkdir -p ~/.local/bin`, and add it to your PATH with `export PATH="$PATH:$HOME/.local/bin"` in your `.bashrc` or `.zshrc` file. |
| 94 | +cp blame-tracker.py ~/.local/bin/ |
| 95 | +cd .. |
| 96 | +rm -rf blame-tracker |
| 97 | +``` |
| 98 | + |
| 99 | +#### Through Curl |
| 100 | + |
| 101 | +```bash |
| 102 | +# If this directory doesn't exist, you can create it with `mkdir -p ~/.local/bin`, and add it to your PATH with `export PATH="$PATH:$HOME/.local/bin"` in your `.bashrc` or `.zshrc` file. |
| 103 | +curl -L https://raw.githubusercontent.com/adam-mcdaniel/blame-tracker/main/blame-tracker.py -o ~/.local/bin/blame-tracker.py |
| 104 | +chmod +x ~/.local/bin/blame-tracker.py |
| 105 | +``` |
0 commit comments