docs: clarify commit author/committer/co-authored-by logic

Co-authored-by: aider (vertex_ai/gemini-2.5-pro-exp-03-25) <noreply@aider.dev>

aider/repo.py

@@ -128,6 +128,70 @@ class GitRepo:
             self.aider_ignore_file = Path(aider_ignore_file)
 
     def commit(self, fnames=None, context=None, message=None, aider_edits=False, coder=None):
+        """
+        Commit the specified files or all dirty files if none are specified.
+
+        Args:
+            fnames (list, optional): List of filenames to commit. Defaults to None (commit all
+                                     dirty files).
+            context (str, optional): Context for generating the commit message. Defaults to None.
+            message (str, optional): Explicit commit message. Defaults to None (generate message).
+            aider_edits (bool, optional): Whether the changes were made by Aider. Defaults to False.
+                                          This affects attribution logic.
+            coder (Coder, optional): The Coder instance, used to access config and model info.
+                                     Defaults to None.
+
+        Returns:
+            tuple(str, str) or None: The commit hash and commit message if successful, else None.
+
+        Attribution Logic:
+        ------------------
+        This method handles Git commit attribution based on configuration flags and whether
+        Aider generated the changes (`aider_edits`).
+
+        Key Concepts:
+        - Author: The person who originally wrote the code changes.
+        - Committer: The person who last applied the commit to the repository.
+        - aider_edits=True: Changes were generated by Aider (LLM).
+        - aider_edits=False: Commit is user-driven (e.g., /commit manually staged changes).
+        - Explicit Setting: A flag (--attribute-...) is set to True or False via command line
+          or config file.
+        - Implicit Default: A flag is not explicitly set, defaulting to None in args, which is
+          interpreted as True unless overridden by other logic.
+
+        Flags:
+        - --attribute-author: Modify Author name to "User Name (aider)".
+        - --attribute-committer: Modify Committer name to "User Name (aider)".
+        - --attribute-co-authored-by: Add "Co-authored-by: aider (<model>) <noreply@aider.dev>"
+          trailer to the commit message.
+
+        Behavior Summary:
+
+        1. When aider_edits = True (AI Changes):
+           - If --attribute-co-authored-by=True:
+             - Co-authored-by trailer IS ADDED.
+             - Author/Committer names are NOT modified by default (co-authored-by takes precedence).
+             - EXCEPTION: If --attribute-author/--attribute-committer is EXPLICITLY True,
+               the respective name IS modified (explicit overrides precedence).
+           - If --attribute-co-authored-by=False:
+             - Co-authored-by trailer is NOT added.
+             - Author/Committer names ARE modified by default (implicit True).
+             - EXCEPTION: If --attribute-author/--attribute-committer is EXPLICITLY False,
+               the respective name is NOT modified.
+
+        2. When aider_edits = False (User Changes):
+           - --attribute-co-authored-by is IGNORED (trailer never added).
+           - Author name is NEVER modified (--attribute-author ignored).
+           - Committer name IS modified by default (implicit True, as Aider runs `git commit`).
+           - EXCEPTION: If --attribute-committer is EXPLICITLY False, the name is NOT modified.
+
+        Resulting Scenarios:
+        - Standard AI edit (defaults): Co-authored-by=False -> Author=You(aider), Committer=You(aider)
+        - AI edit with Co-authored-by (default): Co-authored-by=True -> Author=You, Committer=You, Trailer added
+        - AI edit with Co-authored-by + Explicit Author: Co-authored-by=True, --attribute-author -> Author=You(aider), Committer=You, Trailer added
+        - User commit (defaults): aider_edits=False -> Author=You, Committer=You(aider)
+        - User commit with explicit no-committer: aider_edits=False, --no-attribute-committer -> Author=You, Committer=You
+        """
         if not fnames and not self.repo.is_dirty():
             return