Skip to content

Commit

Permalink
Fix README and args
Browse files Browse the repository at this point in the history 
- Update CLI formatting and accepted args
- Update README to match current functionality
- Add warnings and issue links for features not implemented

FIXES #9
  • Loading branch information
@tomfa
tomfa committed Aug 1, 2020
1 parent c754813 commit 5bc1b2a
Show file tree
Hide file tree
Showing 3 changed files with 149 additions and 153 deletions.
132 changes: 64 additions & 68 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,16 @@ npm install -g git-csv-timesheet
## Basic usage

```bash
$ timesheet
$ timesheet --authors me@example.com --since thismonth
date;hours
2020-07-01;7.5
2020-07-02;8
2020-07-03;10

$ timesheet \
--authors me@example.com \
--since thismonth \
--repositories /usr/repos/frontend,/usr/repos/backend
date;hours
2020-07-01;7.5
2020-07-02;8
Expand Down Expand Up @@ -85,90 +94,75 @@ The algorithm comes from [@kimmobrunfeldt/git-hours](https://github.com/kimmobru
## Options

### Advanced usage
```
Usage: timesheet [options]
Usage: timesheet [options]

Options:
-h, --help output usage information
-V, --version output the version number
-c, --config=[path-to-config] reads config from this path
-f, --from=[YYYY-MM-DD] counts commits from this date (including)
-t, --to=[YYYY-MM-DD] counts commits from to date (excluding)
-M, --month=[1...12] counts commits from this month (defaults to current month, unless year is specified. can not be used with week, from or to)
-Y, --year=[YYYY] counts commits from this year (defaults to current year)
-W, --week=[1-53] counts commits from this week (can not be used with month, from or to)
-T, --tasks splits usage inside repository based on #task references.
-d, --max-commit-diff=[max-commit-diff] maximum difference in minutes between commits counted to one session. Default: 120
-a, --first-commit-add=[first-commit-add] how many minutes first commit of session should add to total. Default: 120
-m, --merge-request=[false|true] Include merge requests into calculation. Default: true

Examples:

- Estimate hours of project

$ timesheet

- Estimate hours in repository where developers commit more seldom: they might have 4h(240min) pause between commits

$ timesheet --max-commit-diff 240

- Estimate hours in repository where developer works 5 hours before first commit in day

$ timesheet --first-commit-add 300

- Estimate hours betwen two dates

$ timesheet --from=2020-01-03 --to=2020-03-05

- Estime hours for a certain month
Options:
-V, --version output the version number
-a, --authors [email@gmail.com] Only care about commits from these
emails.
-d, --max-commit-diff [minutes] max minutes between commits counted as
one session.
[default: 180]
-f, --first-commit-add [minutes] how many minutes first commit of
session should add to total.
[default: 60]
-s, --since [date] Analyze data since date (including).
[today|lastweek|thismonth|yyyy-mm-dd]
[default: always]
-u, --until [date] Analyze data until date (excluding).
[today|lastweek|thismonth|yyyy-mm-dd]
[default: always]
-r, --repositories [path,other-path] Git repositories to analyze.
[default: .]
-e, --email [emailOther=emailMain] Group person by email.
-m, --merge-request [false|true] Include merge requests into
calculation.
[default: true]
-b, --branch [branch-name] Analyze only data on the specified
branch.
[default: null]
-i, --ignore-timesheetrc Ignores .timesheetrc from home
directory.
[default: false]
-h, --help display help for command
$ timesheet --month=1
Examples:
- Estime hours spent on each task
- Estimate hours of project
$ timesheet --tasks
$ timesheet
- Estimate hours work in repository on the "master" branch
- Estimate hours by me@example.com
$ timesheet --branch master
$ timesheet -a me@example.com
### Time range
- Estimate hours where developers commit seldom
[git-csv-timesheet](https://github.comt/tomfa/git-csv-timesheet) will by default print out time spent this month in the current repository.
You can override the time frame with `--week`, `--month`, `--year`, `--from` and `--to` or `--all`.
$ timesheet --max-commit-diff 240
```bash
# Prints current week
timesheet --week
- Estimate hours in when working 5 hours before first commit of day
# Prints week 36 in this year
timesheet --week=36
$ timesheet --first-commit-add 300
# Prints february of this year
timesheet --month=2
- Estimate hours work this month
# Prints current year
timesheet --year
$ timesheet --since thismonth
# Prints whole of 2019
timesheet --year=2019
- Estimate hours work until 2020-01-01
# Prints between 3rd of Jan -> 5th of Mar (YYYY-MM-DD)
# This includes whole of 2020-01-03, but NOT 2020-03-05
timesheet --from=2020-01-03 --to=2020-03-05

# Prints data for all time up to today
timesheet --all
$ timesheet --until 2020-01-01
```

## Config

### .timesheetrc config

By default, the command will check the current git repository. You can also summarize multiple repositories by specifying a config.
By default, the repository parameter will check the current git repository.
You can also summarize multiple repositories by specifying a config.

```bash
➜ git:(master) timesheet --week --config=~/.timesheetrc
➜ git:(master) timesheet --week --config ~/.timesheetrc
date;project;repository;hours
2020-07-27;Personal blog;@tomfa/notes;3.5
2020-07-27;Personal blog;@tomfa/notes-frontend;1
Expand Down Expand Up @@ -215,17 +209,19 @@ The config above will:
- count commits made by "me@gmail.com" and "me@oldworkplace.com" towards the author "me@companymail.com"
- add 60 minutes before first commits (for a day)
- "glue together" commits that are less than 2 hours between.
- count merges as your commit (except for `/Users/tomfa/repos/backend`, where it's overriden)
- count 1 repo for a "Unspecified" project (`/Users/tomfa/repos/random-project`)
- count 2 repos each for the two projects `Client 1"` and `Personal blog`.
- for the two `Client 1` repos: it will split up the work into tasks specified in commits (see below.)
- count merges as your commit (TODO: [#16](https://github.com/tomfa/git-csv-timesheet/issues/16))except for `/Users/tomfa/repos/backend`, where it's overriden)
- TODO: [#17](https://github.com/tomfa/git-csv-timesheet/issues/10) count 1 repo for a "Unspecified" project (`/Users/tomfa/repos/random-project`)
- TODO: [#17](https://github.com/tomfa/git-csv-timesheet/issues/10) count 2 repos each for the two projects `Client 1"` and `Personal blog`.
- TODO: [#16](https://github.com/tomfa/git-csv-timesheet/issues/16) [#10](https://github.com/tomfa/git-csv-timesheet/issues/10) [for the two `Client 1` repos: it will split up the work into tasks specified in commits (see below.)

### Task tracking

_TODO: [#10](https://github.com/tomfa/git-csv-timesheet/issues/10) This feature is not yet implemented._

If you need to specify what you've worked on (_I'm sorry_), [git-csv-timesheet](https://github.comt/tomfa/git-csv-timesheet) can look for `#` in your commits to categorise work based on individual tasks.

```bash
> timesheet --week --config=~/.timesheetrc --tasks
> timesheet --week --config ~/.timesheetrc --tasks
date;project;repository;task;hours
2020-07-27;Personal blog;@tomfa/notes;#14;1.5
2020-07-27;Personal blog;@tomfa/notes;#13;2.5
Expand Down
161 changes: 79 additions & 82 deletions src/bin/args.ts
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { Config, EmailAliases } from '../types';
import { Config } from '../types';
import { defaultConfig } from '../config';
import logger from "../logger";
import logger from '../logger';

const program = require('commander');

Expand All @@ -13,112 +13,97 @@ export function parseCommandLineArgs(): Partial<Config> {
.version(require('../../package.json').version)
.usage('[options]')
.option(
'-d, --max-commit-diff [max-commit-diff]',
'maximum difference in minutes between commits counted to one' +
' session. Default: ' +
defaultConfig.maxCommitDiffInMinutes,
'-a, --authors [email@gmail.com]',
'Only care about commits from these emails.' +
wrapInDefault(defaultConfig.authors),
parseArrayArg(','),
)
.option(
'-d, --max-commit-diff [minutes]',
'max minutes between commits counted as one session.' +
wrapInDefault(defaultConfig.maxCommitDiffInMinutes),
int,
)
.option(
'-a, --first-commit-add [first-commit-add]',
'-f, --first-commit-add [minutes]',
'how many minutes first commit of session should add to total.' +
' Default: ' +
defaultConfig.firstCommitAdditionInMinutes,
wrapInDefault(defaultConfig.firstCommitAdditionInMinutes),
int,
)
.option(
'-s, --since [since-certain-date]',
'Analyze data since certain date.' +
' [always|yesterday|today|lastweek|thisweek|yyyy-mm-dd] Default: ' +
defaultConfig.since,
'-s, --since [date]',
'Analyze data since date (including). \n' +
'[today|lastweek|thismonth|yyyy-mm-dd]' +
wrapInDefault(defaultConfig.since),
String,
)
.option(
'-e, --email [emailOther=emailMain,emailSecondary=emailMail]',
'Group person by email address.' + ' Default: none',
parseDictArg(',', '='),
)
.option(
'-u, --until [until-certain-date]',
'Analyze data until certain date.' +
' [always|yesterday|today|lastweek|thisweek|yyyy-mm-dd] Default: ' +
defaultConfig.until,
'-u, --until [date]',
'Analyze data until date (excluding). \n' +
'[today|lastweek|thismonth|yyyy-mm-dd]' +
wrapInDefault(defaultConfig.until),
String,
)
.option(
'-m, --merge-request [false|true]',
'Include merge requests into calculation. ' +
' Default: ' +
defaultConfig.countMerges,
parseBooleanArg,
)
.option(
'-r, --repositories [path,other-path]',
'Git repositories to analyze.' +
' Default: ' +
defaultConfig.repositories.join(' and '),
wrapInDefault(defaultConfig.repositories.join(',')),
parseArrayArg(','),
)
.option(
'-b, --branch [branch-name]',
'Analyze only data on the specified branch. Default: ' +
defaultConfig.branch,
String,
'-e, --email [emailOther=emailMain]',
'Group person by email.',
parseDictArg(',', '='),
)
.option(
'-A, --authors [email@gmail.com,email@example.com]',
'Only care about commits from these emails. Default: ' +
(defaultConfig.authors.length > 0
? defaultConfig.authors.join(',')
: 'all'),
parseArrayArg(','),
'-m, --merge-request [false|true]',
'Include merge requests into calculation.' +
wrapInDefault(defaultConfig.countMerges),
parseBooleanArg,
)
.option(
'-b, --branch [branch-name]',
'Analyze only data on the specified branch.' +
wrapInDefault(defaultConfig.branch),
String,
)
.option(
'-i, --ignore-timesheetrc',
'Ignores .timesheetrc fi;e from home directory. Default: ' +
defaultConfig.ignoreConfigFile,
parseArgTrueIfSpecified
'Ignores .timesheetrc from home directory.' +
wrapInDefault(defaultConfig.ignoreConfigFile),
parseArgTrueIfSpecified,
);

program.on('--help', function () {
console.log(' Examples:');
console.log('');
console.log(' - Estimate hours of project');
console.log('');
console.log(' $ git hours');
console.log('');
console.log(
' - Estimate hours in repository where developers commit' +
' more seldom: they might have 4h(240min) pause between commits',
);
console.log('');
console.log(' $ git hours --max-commit-diff 240');
console.log('');
console.log(
' - Estimate hours in repository where developer works 5' +
' hours before first commit in day',
);
console.log('');
console.log(' $ git hours --first-commit-add 300');
console.log('');
console.log(' - Estimate hours work in repository since yesterday');
console.log('');
console.log(' $ git hours --since yesterday');
console.log('');
console.log(' - Estimate hours work in repository since 2015-01-31');
console.log('');
console.log(' $ git hours --since 2015-01-31');
console.log('');
console.log(
' - Estimate hours work in repository on the "master" branch',
);
console.log('');
console.log(' $ git hours --branch master');
console.log('');
console.log(
' For more details, visit https://github.com/kimmobrunfeldt/git-hours',
);
console.log('');
console.log(`
Examples:
- Estimate hours of project
$ timesheet
- Estimate hours by me@example.com
$ timesheet -a me@example.com
- Estimate hours where developers commit seldom
$ timesheet --max-commit-diff 240
- Estimate hours in when working 5 hours before first commit of day
$ timesheet --first-commit-add 300
- Estimate hours work this month
$ timesheet --since thismonth
- Estimate hours work until 2020-01-01
$ timesheet --until 2020-01-01
For more details, visit https://github.com/tomfa/git-csv-timesheet
`);
});

program.parse(process.argv);
Expand Down Expand Up @@ -174,3 +159,15 @@ const parseDictArg = (separator: string, keyValueSeparator: string) => (
return map;
};
const parseArgTrueIfSpecified = () => true;
const wrapInDefault = (value: any): string => {
if (value === undefined) {
return '';
}
if (value instanceof Array) {
if (value.length === 0) {
return '';
}
value = value.join(',');
}
return `\n[default: ${value}]`;
};
Loading

0 comments on commit 5bc1b2a

Please sign in to comment.