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, arg_required_else_help = true, before_help = BEFORE_HELP, after_help = AFTER_HELP
19)]
20pub(super) struct Arguments {
21    /// The URL of the GitLab repository you want to export time logs from.
22    #[arg(value_name = "URL", env = "GITLAB_URL")]
23    pub(super) url: String,
24
25    /// A GitLab access token. Needed if the repository is not public.
26    /// Can be a personal, group, or repository access token.
27    #[arg(short, long, env = "GITLAB_TOKEN")]
28    pub(super) token: Option<String>,
29
30    /// Comma-separated list of GitLab labels to filter by. All other labels will be grouped under
31    /// "Others". If your labels contain spaces, delimit them with `"`:
32    /// `--labels "Epic 1",Documentation`. The labels are case-sensitive.
33    /// If not set, all labels are shown.
34    #[arg(short, long, value_delimiter = ',', env = "GITLAB_LABELS")]
35    pub(super) labels: Vec<String>,
36
37    /// Displays the problems with the time logs found during validation.
38    #[arg(long)]
39    pub(super) validation_details: bool,
40
41    /// When validating time logs, the maximum number of hours a time log should have.
42    #[arg(long, default_value = "10")]
43    pub(super) validation_max_hours: u16,
44
45    /// The subcommand to run.
46    #[command(subcommand)]
47    pub(super) command: Option<Command>,
48}
49
50#[derive(Subcommand)]
51pub(super) enum Command {
52    /// Export the time logs to a CSV file.
53    Export {
54        /// The path to the CSV file. If not set, the file will be saved to the current working
55        /// directory with the name `timelogs.csv`.
56        #[arg(short, long, default_value = "timelogs.csv")]
57        output: PathBuf,
58    },
59    /// Generate charts from your time logs as HTML and SVG. Creates the following charts:
60    /// Time spent per user, per milestone, per label, per user/label, per type (issue or MR),
61    /// per type/user, estimates/actual time per label and burndown charts (total and per user).
62    Charts {
63        #[command(flatten)]
64        chart_options: ChartOptionsArgs,
65    },
66    /// Generate an HTML file with charts and statistics about the time logs.
67    Dashboard {
68        #[command(flatten)]
69        chart_options: ChartOptionsArgs,
70    },
71}
72
73/// Shared options for generating charts.
74#[derive(Args)]
75#[clap(disable_help_flag = true)]
76pub(super) struct ChartOptionsArgs {
77    /// The width of the charts.
78    #[arg(short, long, default_value = "800")]
79    pub(super) width: u16,
80
81    /// The height of the charts.
82    #[arg(short, long, default_value = "480")]
83    pub(super) height: u16,
84
85    /// Create your own theme for the charts at <https://echarts.apache.org/en/theme-builder.html>
86    /// and specify the path of the resulting JSON file. If not set, the charts are created using
87    /// default settings.
88    #[arg(long, value_name = "PATH_TO_THEME_JSON", env)]
89    pub(super) theme_json: Option<PathBuf>,
90
91    /// The path the charts will be written to. If not set, a "charts" directory will be created in
92    /// the current working directory.
93    #[arg(short, long, default_value = "charts")]
94    pub(super) output: PathBuf,
95
96    /// The number of sprints the project is planned to take for the burndown chart.
97    /// If sprints are not used in your project, enter the number of weeks that the project has.
98    #[arg(long, value_name = "NUMBER_OF_SPRINTS", env)]
99    pub(super) sprints: u16,
100
101    /// The number of weeks each sprint lasts. Required for the burndown charts.
102    #[arg(long, env)]
103    pub(super) weeks_per_sprint: u16,
104
105    /// The number of hours a person is expected to work in total. Required for the burndown charts.
106    #[arg(long, env)]
107    pub(super) hours_per_person: f32,
108
109    /// The start date of the burndown chart.
110    /// If not set, the date of the earliest time log is used.
111    #[arg(long, value_name = "YYYY-MM-DD")]
112    pub(super) start_date: Option<NaiveDate>,
113
114    // Implements help only for --help, not for -h
115    /// Print help
116    #[clap(long, action = clap::ArgAction::HelpLong)]
117    help: Option<bool>,
118}
gitlab_time_report_cli/arguments.rs

gitlab_time_report_cli/
arguments.rs
