Support git submodules; Add "always" option; Fix compatibility with ESPHome 2024.3.1 and later; Update example

README.md

@@ -19,7 +19,7 @@ external_components:
 
 text_sensor:
   - platform: git_ref
-    name: "${friendly_name} Git Ref"
+    name: "Git Ref"
     long: true
     all: true
     abbrev: 16
@@ -36,6 +36,7 @@ All of them are **optional**.
 
 - **abbrev** (Int): Instead of using the default number of hexadecimal digits (which will vary according to the number of objects in the repository with a default of 7) of the abbreviated object name, use <n> digits, or as many digits as needed to form a unique object name. An <n> of 0 will suppress long format, only showing the closest tag.
 - **all** (Boolean): Instead of using only the annotated tags, use any ref found in refs/ namespace. This option enables matching any known branch, remote-tracking branch, or lightweight tag.
+- **always** (Boolean): Show uniquely abbreviated commit object as fallback. Useful to avoid the "No names found, cannot describe anything." error in case no git tag exists.
 - **broken** (String): Describe the state of the working tree. If a repository is corrupt and Git cannot determine if there is local modification, Git will error out, unless ‘--broken’ is given, which appends the suffix provided by this option instead.
 - **commit-ish** (String): Commit-ish object names to describe. Defaults to HEAD if omitted.
 - **dirty** (String): Describe the state of the working tree[<sup>[1]</sup>](#dirty-parsing). If the working tree has local modifications the suffix provided by this option is appended to it.
@@ -44,6 +45,7 @@ All of them are **optional**.
 - **unversioned** (String, default=`-UNVERSIONED`): Suffix to append when the device config file is not tracked by Git.
 
 ### Dirty parsing
+
 When using the `dirty` option, _only_ **tracked** files that are relevant for the configuration are considered!
 
 This includes the following:
@@ -55,3 +57,4 @@ This includes the following:
 
 If there are uncommitted changes to any of these files, the provided `dirty` suffix will be added to the `git describe` output.
 
+When git submodules are included, the detection which files are actually used is currently not implemented and dirty is reporeted if any file or even a file in a git submodules has uncommitted changes.

components/git_ref/text_sensor.py

@@ -4,7 +4,6 @@
 import yaml
 
 from esphome import git, yaml_util, util
-from esphome.config_helpers import read_config_file
 
 from esphome.core import CORE
 from esphome.components import text_sensor
@@ -36,6 +35,7 @@
             cv.Optional("all", default=False): cv.boolean,
             cv.Optional("tags", default=False): cv.boolean,
             cv.Optional("long", default=False): cv.boolean,
+            cv.Optional("always", default=False): cv.boolean,
             cv.Optional("abbrev"): cv.positive_int,
         }
     )
@@ -66,6 +66,15 @@ def is_config_versioned():
     return git_ls_files == config_path_trimmed
 
 
+def is_superproject_using_git_submodules():
+    GIT_SUBMODULES = git.run_git_command(
+        ["git", "submodule", "status", "--cached"],
+    )
+    _LOGGER.debug("git submodules: %s", GIT_SUBMODULES)
+
+    return GIT_SUBMODULES != ""
+
+
 def get_git_diff(GIT_DIR, cached=False):
     DIFF_COMMAND = ["git", "diff", "--name-only"]
     if cached:
@@ -238,6 +247,8 @@ def produce_git_describe(config):
         COMMAND.append("--tags")
     if config.get("long", False):
         COMMAND.append("--long")
+    if config.get("always", False):
+        COMMAND.append("--always")
 
     if "abbrev" in config:
         COMMAND.append(f"--abbrev={config['abbrev']}")
@@ -249,17 +260,22 @@ def produce_git_describe(config):
     if "dirty" in config:
         # COMMAND.append(f"--dirty={config['dirty']}")
         if is_config_versioned():
-            diff_paths = get_git_diff_file_paths(config)
-            config_paths = get_config_file_paths(config)
-            _LOGGER.info(
-                "Checking git Diffs: \n%s\n\nAgainst files in config: \n%s\n",
-                diff_paths,
-                config_paths,
-            )
-            for file in config_paths:
-                if file in diff_paths:
-                    dirty_postfix = config["dirty"]
-                    _LOGGER.warning("Config dirty: '%s' has changes", file)
+            if is_superproject_using_git_submodules():
+                # Git submodules are involved. Using simplified dirty status
+                # that does not check what files are actually used.
+                COMMAND.append(f"--dirty={config['dirty']}")
+            else:
+                diff_paths = get_git_diff_file_paths(config)
+                config_paths = get_config_file_paths(config)
+                _LOGGER.info(
+                    "Checking git Diffs: \n%s\n\nAgainst files in config: \n%s\n",
+                    diff_paths,
+                    config_paths,
+                )
+                for file in config_paths:
+                    if file in diff_paths:
+                        dirty_postfix = config["dirty"]
+                        _LOGGER.warning("Config dirty: '%s' has changes", file)
         else:
             _LOGGER.warning("Config File '%s' is unversioned!", CORE.config_path)
             dirty_postfix = config["unversioned"]

example.yaml

@@ -8,7 +8,7 @@ esp32:
   board: wemos_d1_mini32
   framework:
     type: arduino
-  
+
 external_components:
   - source: github://RoboMagus/esphome-gitref-sensor
 
@@ -26,8 +26,8 @@ ota:
 
 text_sensor:
   - platform: git_ref
-    name: "${friendly_name} Git Ref"
+    name: "Git Ref"
     long: true
     all: true
     abbrev: 16
-    dirty: "-dirty"
+    dirty: "-dirty"