|
| 1 | +# Git Author Configuration Guide |
| 2 | + |
| 3 | +This guide explains how to configure git author information so your commits are properly attributed to you in the repository and on GitHub. |
| 4 | + |
| 5 | +## Quick Setup |
| 6 | + |
| 7 | +Set your name and email that will appear on all your commits: |
| 8 | + |
| 9 | +```bash |
| 10 | +git config user.name "Your Name" |
| 11 | +git config user.email "[email protected]" |
| 12 | +``` |
| 13 | + |
| 14 | +## Understanding Git Author Attribution |
| 15 | + |
| 16 | +When you make commits to a Git repository, Git records: |
| 17 | +1. **Author Name** - Your display name |
| 18 | +2. **Author Email** - Your email address |
| 19 | +3. **Timestamp** - When the commit was made |
| 20 | + |
| 21 | +This information is permanently recorded in the git history and displayed on GitHub. |
| 22 | + |
| 23 | +## Configuration Levels |
| 24 | + |
| 25 | +Git has three configuration levels: |
| 26 | + |
| 27 | +### 1. System-wide (all users) |
| 28 | +```bash |
| 29 | +git config --system user.name "Your Name" |
| 30 | +git config --system user.email "[email protected]" |
| 31 | +``` |
| 32 | + |
| 33 | +### 2. Global (your user account) |
| 34 | +```bash |
| 35 | +git config --global user.name "Your Name" |
| 36 | +git config --global user.email "[email protected]" |
| 37 | +``` |
| 38 | + |
| 39 | +### 3. Repository-specific (recommended for this project) |
| 40 | +```bash |
| 41 | +cd /path/to/empathy |
| 42 | +git config user.name "Your Name" |
| 43 | +git config user.email "[email protected]" |
| 44 | +``` |
| 45 | + |
| 46 | +## Best Practices |
| 47 | + |
| 48 | +### Use Your GitHub Email |
| 49 | + |
| 50 | +To ensure your commits link to your GitHub account: |
| 51 | + |
| 52 | +1. Find your GitHub email: |
| 53 | + - Go to GitHub Settings → Emails |
| 54 | + - Use your public email or GitHub-provided noreply email |
| 55 | + |
| 56 | +2. Configure git: |
| 57 | +```bash |
| 58 | +git config user.name "Your GitHub Username" |
| 59 | +git config user.email "[email protected]" |
| 60 | +``` |
| 61 | + |
| 62 | +### Private Email |
| 63 | + |
| 64 | +If you want to keep your email private, GitHub provides a no-reply email: |
| 65 | +``` |
| 66 | +<username>@users.noreply.github.com |
| 67 | +``` |
| 68 | + |
| 69 | +Or with ID: |
| 70 | +``` |
| 71 | +<ID+username>@users.noreply.github.com |
| 72 | +``` |
| 73 | + |
| 74 | +Example: |
| 75 | +```bash |
| 76 | +git config user.name "Jane Developer" |
| 77 | +git config user.email "[email protected]" |
| 78 | +``` |
| 79 | + |
| 80 | +## Verifying Your Configuration |
| 81 | + |
| 82 | +Check your current settings: |
| 83 | + |
| 84 | +```bash |
| 85 | +git config user.name |
| 86 | +git config user.email |
| 87 | +``` |
| 88 | + |
| 89 | +View all git configurations: |
| 90 | +```bash |
| 91 | +git config --list |
| 92 | +``` |
| 93 | + |
| 94 | +## Changing Author for Existing Commits |
| 95 | + |
| 96 | +**Warning:** Rewriting git history can cause problems in shared repositories. Only do this if you understand the implications. |
| 97 | + |
| 98 | +### For the Last Commit |
| 99 | + |
| 100 | +```bash |
| 101 | +git commit --amend --author= "Your Name <[email protected]>" |
| 102 | +``` |
| 103 | + |
| 104 | +### For Multiple Commits |
| 105 | + |
| 106 | +Use interactive rebase (advanced): |
| 107 | +```bash |
| 108 | +git rebase -i HEAD~N # N = number of commits to go back |
| 109 | +``` |
| 110 | + |
| 111 | +### For All Commits in a Branch |
| 112 | + |
| 113 | +```bash |
| 114 | +git filter-branch --env-filter ' |
| 115 | + |
| 116 | +CORRECT_NAME="Your Name" |
| 117 | + |
| 118 | +
|
| 119 | +if [ "$GIT_COMMITTER_EMAIL" = "$OLD_EMAIL" ] |
| 120 | +then |
| 121 | + export GIT_COMMITTER_NAME="$CORRECT_NAME" |
| 122 | + export GIT_COMMITTER_EMAIL="$CORRECT_EMAIL" |
| 123 | +fi |
| 124 | +if [ "$GIT_AUTHOR_EMAIL" = "$OLD_EMAIL" ] |
| 125 | +then |
| 126 | + export GIT_AUTHOR_NAME="$CORRECT_NAME" |
| 127 | + export GIT_AUTHOR_EMAIL="$CORRECT_EMAIL" |
| 128 | +fi |
| 129 | +' --tag-name-filter cat -- --branches --tags |
| 130 | +``` |
| 131 | + |
| 132 | +**Note:** After rewriting history, you'll need to force push: |
| 133 | +```bash |
| 134 | +git push --force-with-lease origin your-branch |
| 135 | +``` |
| 136 | + |
| 137 | +## Using .mailmap |
| 138 | + |
| 139 | +The repository includes a `.mailmap` file that helps Git map different author identities to a canonical name and email. This is useful when: |
| 140 | +- You've used different email addresses in commits |
| 141 | +- You want to consolidate multiple identities |
| 142 | +- You need to update how authors appear in logs |
| 143 | + |
| 144 | +The `.mailmap` format: |
| 145 | +``` |
| 146 | + |
| 147 | +``` |
| 148 | + |
| 149 | +## GitHub Integration |
| 150 | + |
| 151 | +### Linking Commits to Your Profile |
| 152 | + |
| 153 | +For commits to show up on your GitHub profile: |
| 154 | + |
| 155 | +1. **Email must be verified** in GitHub settings |
| 156 | +2. **Email must match** one in your GitHub account |
| 157 | +3. **Email can be** your GitHub noreply address |
| 158 | + |
| 159 | +### Checking Attribution |
| 160 | + |
| 161 | +After committing, check on GitHub: |
| 162 | +1. Push your commits |
| 163 | +2. View the commit on GitHub |
| 164 | +3. Your avatar and username should appear if properly configured |
| 165 | + |
| 166 | +## Troubleshooting |
| 167 | + |
| 168 | +### Commits Don't Show on My Profile |
| 169 | + |
| 170 | +1. Verify your email is added to GitHub: |
| 171 | + - GitHub Settings → Emails → Add email address |
| 172 | + |
| 173 | +2. Check git configuration: |
| 174 | +```bash |
| 175 | +git config user.email |
| 176 | +``` |
| 177 | + |
| 178 | +3. Ensure email matches exactly (case-sensitive) |
| 179 | + |
| 180 | +### Wrong Author on Commits |
| 181 | + |
| 182 | +1. Check current configuration: |
| 183 | +```bash |
| 184 | +git config user.name |
| 185 | +git config user.email |
| 186 | +``` |
| 187 | + |
| 188 | +2. Update for future commits: |
| 189 | +```bash |
| 190 | +git config user.name "Correct Name" |
| 191 | +git config user.email "[email protected]" |
| 192 | +``` |
| 193 | + |
| 194 | +3. For existing commits, see "Changing Author for Existing Commits" above |
| 195 | + |
| 196 | +### Multiple Git Identities |
| 197 | + |
| 198 | +If you work on multiple projects with different identities, use repository-specific config: |
| 199 | + |
| 200 | +```bash |
| 201 | +# Project 1 |
| 202 | +cd /path/to/project1 |
| 203 | +git config user.name "Work Name" |
| 204 | +git config user.email "[email protected]" |
| 205 | + |
| 206 | +# Project 2 |
| 207 | +cd /path/to/project2 |
| 208 | +git config user.name "Personal Name" |
| 209 | +git config user.email "[email protected]" |
| 210 | +``` |
| 211 | + |
| 212 | +## Additional Resources |
| 213 | + |
| 214 | +- [Git Configuration Documentation](https://git-scm.com/docs/git-config) |
| 215 | +- [GitHub Managing Commit Signature Verification](https://docs.github.com/en/authentication/managing-commit-signature-verification) |
| 216 | +- [Git mailmap Documentation](https://git-scm.com/docs/gitmailmap) |
| 217 | + |
| 218 | +## Questions? |
| 219 | + |
| 220 | +If you have questions about git configuration or author attribution, please: |
| 221 | +- Check [GitHub Discussions](https://github.com/Smart-AI-Memory/empathy/discussions) |
| 222 | +- Review [Contributing Guidelines](../CONTRIBUTING.md) |
| 223 | +- Open an issue for documentation improvements |
0 commit comments