fix: let commit_begin back to work and add docs (#129)

Author: shenxianpeng

docs/source/configuration.rst

@@ -0,0 +1,44 @@
+
+Configuration
+=============
+
+You can create a ``gitstats.conf`` file in the current directory to customize the configuration.
+
+* ``max_domains`` - Maximum number of domains to display in "Domains by Commits". Default: ``10``.
+* ``max_ext_length`` - Maximum length of file extensions shown in statistics. Default: ``10``.
+* ``style`` - CSS stylesheet for the generated report. Default: ``gitstats.css``.
+* ``max_authors`` - Maximum number of authors to list in "Authors". Default: ``20``.
+* ``authors_top`` - Number of top authors to highlight. Default: ``5``.
+* ``commit_begin`` - Start of commit range (empty = include all commits). For example, ``10`` for last 10 commits. Default: ``""`` (empty).
+* ``commit_end`` - End of commit range. Default: ``HEAD``.
+* ``linear_linestats`` - Enable linear history for line statistics (``1`` = enabled, ``0`` = disabled). Default: ``1``.
+* ``project_name`` - Project name to display (default: repository directory name). Default: ``""`` (empty).
+* ``processes`` - Number of parallel processes to use when gathering data. Default: ``8``.
+* ``start_date`` - Starting date for commits, passed as --since to Git (optional). Format: ``YYYY-MM-DD``. Default: ``""`` (empty).
+
+Here is an example ``gitstats.conf`` file:
+
+.. code-block:: ini
+
+   [gitstats]
+   max_domains = 10
+   max_ext_length = 10
+   style = gitstats.css
+   max_authors = 20
+   authors_top = 5
+   commit_begin = 10
+   commit_end = HEAD
+   linear_linestats = 1
+   project_name =
+   processes = 8
+   start_date =
+
+You can also override configuration values using the ``-c key=value`` option when running the ``gitstats`` command.
+
+For example:
+
+.. code-block:: bash
+
+   gitstats . report -c max_authors=10 -c authors_top=3
+
+This command will generate a report with a maximum of 10 authors displayed and the top 3 authors shown.

docs/source/index.rst

@@ -11,6 +11,7 @@ Welcome to GitStats documentation!
 
    installation
    usage
+   configuration
    integration
    faq
 

gitstats/main.py

@@ -139,17 +139,30 @@ def collect(self, dir):
         DataCollector.collect(self, dir)
 
         self.total_authors += int(
-            get_pipe_output(["git shortlog -s %s" % get_log_range(), "wc -l"])
+            get_pipe_output(
+                ["git shortlog -s %s" % get_log_range("HEAD", False), "wc -l"]
+            )
         )
         # self.total_lines = int(getoutput('git-ls-files -z |xargs -0 cat |wc -l'))
 
         # tags
+        # Only include tags that are reachable within the commit range
+        commit_range = get_commit_range("HEAD", False)
+        tag_commits = (
+            get_pipe_output([f"git rev-list {commit_range}"]).strip().split("\n")
+        )
+        tag_commits_set = set(tag_commits) if tag_commits[0] else set()
+
         lines = get_pipe_output(["git show-ref --tags"]).split("\n")
         for line in lines:
             if len(line) == 0:
                 continue
             (hash, tag) = line.split(" ")
 
+            # Only include tags whose commit is in our range
+            if hash not in tag_commits_set:
+                continue
+
             tag = tag.replace("refs/tags/", "")
             output = get_pipe_output(
                 ['git log "%s" --pretty=format:"%%at %%aN" -n 1' % hash]
@@ -170,6 +183,8 @@ def collect(self, dir):
                 }
 
         # collect info on tags, starting from latest
+        # Only collect statistics for commits within our range
+        commit_range = get_commit_range("HEAD", False)
         tags_sorted_by_date_desc = [
             el[1]
             for el in reversed(
@@ -178,15 +193,22 @@ def collect(self, dir):
         ]
         prev = None
         for tag in reversed(tags_sorted_by_date_desc):
-            cmd = 'git shortlog -s "%s"' % tag
+            # Modify command to only include commits within our range
+            cmd = f'git shortlog -s "{tag}"'
             if prev is not None:
-                cmd += ' "^%s"' % prev
+                cmd += f' "^{prev}"'
+            # Intersect with our commit range
+            cmd += f" {commit_range}"
             output = get_pipe_output([cmd])
             if len(output) == 0:
                 continue
             prev = tag
             for line in output.split("\n"):
+                if len(line.strip()) == 0:
+                    continue
                 parts = re.split(r"\s+", line, 2)
+                if len(parts) < 3:
+                    continue
                 commits = int(parts[1])
                 author = parts[2]
                 self.tags[tag]["commits"] += commits
@@ -197,7 +219,7 @@ def collect(self, dir):
         lines = get_pipe_output(
             [
                 'git rev-list --pretty=format:"%%at %%ai %%aN <%%aE>" %s'
-                % get_log_range("HEAD"),
+                % get_log_range("HEAD", False),
                 "grep -v ^commit",
             ]
         ).split("\n")
@@ -335,7 +357,7 @@ def collect(self, dir):
             get_pipe_output(
                 [
                     'git rev-list --pretty=format:"%%at %%T" %s'
-                    % get_log_range("HEAD"),
+                    % get_log_range("HEAD", False),
                     "grep -v ^commit",
                 ]
             )
@@ -448,7 +470,7 @@ def collect(self, dir):
         lines = get_pipe_output(
             [
                 'git log --shortstat %s --pretty=format:"%%at %%aN" %s'
-                % (extra, get_log_range("HEAD"))
+                % (extra, get_log_range("HEAD", False))
             ]
         ).split("\n")
         lines.reverse()
@@ -523,7 +545,7 @@ def collect(self, dir):
         lines = get_pipe_output(
             [
                 'git log --shortstat --date-order --pretty=format:"%%at %%aN" %s'
-                % (get_log_range("HEAD"))
+                % (get_log_range("HEAD", False))
             ]
         ).split("\n")
         lines.reverse()
@@ -804,7 +826,11 @@ def main() -> int:
             key, value = item.split("=", 1)
             if key not in conf:
                 parser.error(f'No such key "{key}" in config')
-            conf[key] = value
+            # Convert numeric strings to integers to match config file behavior
+            if value.isdigit():
+                conf[key] = int(value)
+            else:
+                conf[key] = value
         except ValueError:
             parser.error("Config must be in the form key=value")
 

gitstats/utils.py

@@ -100,9 +100,20 @@ def get_pipe_output(cmds, quiet=False):
 
 def get_commit_range(defaultrange="HEAD", end_only=False):
     if len(conf["commit_end"]) > 0:
-        if end_only or len(conf["commit_begin"]) == 0:
+        commit_begin = conf["commit_begin"]
+
+        # Convert commit_begin to string for consistent handling
+        commit_begin_str = str(commit_begin)
+
+        # If end_only or no commit_begin specified, return just the end
+        if end_only or len(commit_begin_str) == 0:
             return conf["commit_end"]
-        return "%s..%s" % (conf["commit_begin"], conf["commit_end"])
+
+        # Handle numeric commit_begin as "N commits ago"
+        if commit_begin_str.isdigit():
+            commit_begin_str = f"{conf['commit_end']}~{commit_begin_str}"
+
+        return "%s..%s" % (commit_begin_str, conf["commit_end"])
     return defaultrange