gitlab_time_report_cli/
arguments.rs

1//! Contains the CLI arguments for gitlab-time-report.
2
3use chrono::NaiveDate;
4use clap::{Args, Parser, Subcommand};
5use std::path::PathBuf;
6
7const BEFORE_HELP: &str = "\n
8gitlab-time-report exports time logs from Issues and Merge Requests of a GitLab repository \
9to create statistics and charts of your working hours. Use --help on commands to get more information. \
10If no subcommand is used, statistics will be printed directly to your console.";
11
12const AFTER_HELP: &str = "By default, validation of time logs is enabled. \
13It checks for excessive hours, future dates, duplicate time logs and missing summaries.
14If a time log violates any of these rules, it is printed to the console. \
15No automatic correction is performed. You can display the full validation results with --validation-details.";
16
17#[derive(Parser)]
18#[command(version, about, before_help = BEFORE_HELP, after_help = AFTER_HELP,
19    arg_required_else_help = true, subcommand_precedence_over_arg = true
20)]
21pub(super) struct Arguments {
22    /// The URLs of the GitLab repositories you want to export time logs from.
23    /// When using multiple URLs, separate them with a space.
24    #[arg(value_name = "URL", env = "GITLAB_URL")]
25    pub(super) url: Vec<String>,
26
27    /// A GitLab access token. Needed if the repository is not public.
28    /// Can be a personal, group, or repository access token.
29    /// All repositories must be accessible with the same token, using different tokens per
30    /// repository is not supported.
31    #[arg(short, long, env = "GITLAB_TOKEN")]
32    pub(super) token: Option<String>,
33
34    /// Comma-separated list of GitLab labels to filter by. All other labels will be grouped under
35    /// "Others". If your labels contain spaces, delimit them with `"`:
36    /// `--labels "Epic 1",Documentation`. The labels are case-sensitive.
37    /// If not set, all labels are shown.
38    #[arg(short, long, value_delimiter = ',', env = "GITLAB_LABELS")]
39    pub(super) labels: Vec<String>,
40
41    /// Displays the problems with the time logs found during validation.
42    #[arg(long)]
43    pub(super) validation_details: bool,
44
45    /// When validating time logs, the maximum number of hours a time log should have.
46    #[arg(long, default_value = "10")]
47    pub(super) validation_max_hours: u16,
48
49    /// The subcommand to run.
50    #[command(subcommand)]
51    pub(super) command: Option<Command>,
52}
53
54#[derive(Subcommand)]
55pub(super) enum Command {
56    /// Export the time logs to a CSV file.
57    Export {
58        /// The path to the CSV file. If not set, the file will be saved to the current working
59        /// directory with the name `timelogs.csv`.
60        #[arg(short, long, default_value = "timelogs.csv")]
61        output: PathBuf,
62    },
63    /// Generate charts from your time logs as HTML and SVG. Creates the following charts:
64    /// Time spent per user, per milestone, per label, per user/label, per type (issue or MR),
65    /// per type/user, estimates/actual time per label and burndown charts (total and per user).
66    Charts {
67        #[command(flatten)]
68        chart_options: ChartOptionsArgs,
69    },
70    /// Generate an HTML file with charts and statistics about the time logs.
71    Dashboard {
72        #[command(flatten)]
73        chart_options: ChartOptionsArgs,
74    },
75}
76
77/// Shared options for generating charts.
78#[derive(Args)]
79#[clap(disable_help_flag = true)]
80pub(super) struct ChartOptionsArgs {
81    /// The width of the charts.
82    #[arg(short, long, default_value = "800")]
83    pub(super) width: u16,
84
85    /// The height of the charts.
86    #[arg(short, long, default_value = "480")]
87    pub(super) height: u16,
88
89    /// Create your own theme for the charts at <https://echarts.apache.org/en/theme-builder.html>
90    /// and specify the path of the resulting JSON file. If not set, the charts are created using
91    /// default settings.
92    #[arg(long, value_name = "PATH_TO_THEME_JSON", env)]
93    pub(super) theme_json: Option<PathBuf>,
94
95    /// The path the charts will be written to. If not set, a "charts" directory will be created in
96    /// the current working directory.
97    #[arg(short, long, default_value = "charts")]
98    pub(super) output: PathBuf,
99
100    /// The number of sprints the project is planned to take for the burndown chart.
101    /// If sprints are not used in your project, enter the number of weeks that the project has.
102    #[arg(long, value_name = "NUMBER_OF_SPRINTS", env)]
103    pub(super) sprints: u16,
104
105    /// The number of weeks each sprint lasts. Required for the burndown charts.
106    #[arg(long, env)]
107    pub(super) weeks_per_sprint: u16,
108
109    /// The number of hours a person is expected to work in total. Required for the burndown charts.
110    #[arg(long, env)]
111    pub(super) hours_per_person: f32,
112
113    /// The start date of the burndown chart.
114    /// If not set, the date of the earliest time log is used.
115    #[arg(long, value_name = "YYYY-MM-DD")]
116    pub(super) start_date: Option<NaiveDate>,
117
118    // Implements help only for --help, not for -h
119    /// Print help
120    #[clap(long, action = clap::ArgAction::HelpLong)]
121    help: Option<bool>,
122}
gitlab_time_report_cli/arguments.rs

gitlab_time_report_cli/
arguments.rs
