Troubleshooting Git on z/OS

Error: "File is untagged, set the correct file tag" on `git add`

Problem: Git requires files to be tagged on z/OS. Untagged files cause this error during git add.
Solution (Recommended): Tag the file using chtag based on its content.
- Text (ASCII/ISO8859-1): chtag -t -c IBM-819 <file>
- Text (UTF-8): chtag -t -c UTF-8 <file>
- Text (EBCDIC): chtag -t -c IBM-1047 <file> (Use appropriate EBCDIC CCSID)
- Binary: chtag -b <file>
- Tip: The tagfile utility from the zopen community tools can help auto-tag.

Workaround (Caution): Ignore tag mismatches (may hide problems).

git config core.ignorefiletags true # For current repo
git config --global core.ignorefiletags true # For all user repos

Files are Tagged UTF-8 (1208) After Clone

Observation: Cloned text files are tagged as UTF-8 (CCSID 1208).
Explanation: This is Git's default tagging behavior on z/OS for text files.

To Change Default Tagging (e.g., to ISO8859-1 / 819):

git config core.utf8ccsid 819 # Current repo
git config --global core.utf8ccsid 819 # All user repos
export GIT_UTF8_CCSID=819 # Environment variable (overrides)

To Restore Default (UTF-8 / 1208):

git config --unset core.utf8ccsid # Current repo
git config --global --unset core.utf8ccsid # All user repos
unset GIT_UTF8_CCSID # Environment variable

Files are Tagged ISO8859-1 (819) After Clone

Observation: Cloned/checked-out text files are tagged ISO8859-1 (CCSID 819).
Explanation: Likely configured via core.utf8ccsid or GIT_UTF8_CCSID (see previous item).

Solution: Check current settings and reset to default (1208) if needed.

git config --show-origin --get core.utf8ccsid
echo $GIT_UTF8_CCSID
# Use --unset commands from previous item to reset

Error: "fatal: detected dubious ownership in repository" in Shared Group Directory

Problem: Users accessing a shared Git repository owned by another user encounter this error due to Git's security checks.
Explanation: Git (v2.35.2+) prevents operations in repositories not owned by the current user unless explicitly marked safe.
Solution (System-Wide Recommended for Shared Access): An administrator adds the directory to the system Git configuration.
```
# Run as admin/root
git config --system --add safe.directory /path/to/shared/repo
```
z/OS Config Location Issue: The default system config file (e.g., /usr/lpp/IBM/foz/.../etc/gitconfig) might be overwritten on upgrades.
Workaround for Config Location: Use an environment variable (e.g., in /etc/profile) to point to a persistent config file:
```
export GIT_CONFIG_SYSTEM=/etc/gitconfig
# Then add the safe.directory setting to /etc/gitconfig
```
Alternative (Individual User): Each user runs git config --global --add safe.directory /path/to/shared/repo.

Problem: `git clone` (or other SSH command) Prints Garbage Characters and Hangs

Symptom: Running git clone git@... (or another Git command using SSH) connects, prints strange non-text characters (e.g., >ʀ//?ʀ,^/`), and then hangs indefinitely.
Explanation: This commonly happens if the TTY (terminal) device itself has been incorrectly tagged (e.g., as ISO8859-1). With _BPXK_AUTOCVT=ON, z/OS attempts automatic character conversion based on file tags. Applying conversion to the TTY device corrupts the raw communication stream expected by SSH and Git for interactive prompts or progress display, causing garbage output and hangs.
Verification: Check the tagging of your current TTY device:
```
ls -lT $SSH_TTY
```
If this command shows a tag (like t ISO8859-1 T=on), it is the likely cause. TTY devices should normally be untagged.
Solution: Remove the tag from your TTY device (requires appropriate permissions).
```
chtag -r $SSH_TTY
```
After untagging, retry the Git command.

Problem: Existing Repository (created using third party vendor's version of git) fails with IBM Open Enterprise Foundation for z/OS Git

Symptom: Operations fail in a repository previously managed by Third party Git after switching to use newer IBM Open Enterprise Foundation for z/OS Git.
Explanation: Significant version differences can cause incompatibilities, particularly in the index file (.git/index) format. IBM Open Enterprise Foundation for z/OS Git may not understand the index created by the older Third-party Git.
Solution (Rebuild Index): Warning: Back up the repository first (cp -Rp repo repo.bak).
1. cd /path/to/repo
2. Verify you're using IBM Open Enterprise Foundation for z/OS Git (git --version).
3. rm .git/index (Remove the old index).
4. git reset HEAD (Rebuild index from HEAD, keeps working dir changes but unstages them).
5. git status (Verify and re-add files if needed).
Alternative (Aggressive - Discards Changes): git reset --hard HEAD (DANGER: Loses all uncommitted work).