z/OS Extensions

The z/OS extensions for Git enable integration of Git's version control capabilities with the platform-specific requirements of z/OS.

z/OS Encoding Considerations

The Open Enterprise Foundation for z/OS Git tool uses Git's .gitattributes to manage various encodings in the local workspace. This functionality is documented in detail here.

Platform-Specific Encoding with zos-working-tree-encoding

For z/OS-specific settings, use the zos-working-tree-encoding attribute to define encodings exclusively for the z/OS platform:

* text zos-working-tree-encoding=IBM-1047

This configuration ensures files are tagged with IBM-1047 encoding on z/OS. For non-z/OS platforms, files remain in their default encoding (e.g., UTF-8). If both working-tree-encoding and zos-working-tree-encoding are specified, the z/OS-specific attribute takes precedence on z/OS.

Example: Dual Encoding Across Platforms

If you need different encodings for z/OS and non-z/OS platforms, you can define both attributes:

* zos-working-tree-encoding=ibm-1047 working-tree-encoding=iso8859-1

This setup specifies:

  • Files are IBM-1047 encoded on z/OS.
  • Files are ISO8859-1 encoded on other platforms.

General Use of working-tree-encoding

The working-tree-encoding attribute defines the encoding of files in the working tree for all platforms. For example, to convert files from Git's internal UTF-8 encoding to IBM-1047, add the following to your .gitattributes file:

* text working-tree-encoding=IBM-1047

This ensures all files are tagged with IBM-1047 encoding upon checkout. You can verify file tags using:

ls -lT

If no encoding is specified, the default is UTF-8 (CCSID 1208). To see all supported encodings, run:

iconv -l

Important Note

When adding files with git add, ensure the z/OS file tag matches the working-tree-encoding. Mismatched encodings may result in errors.

Default Encodings and File Tags (CCSIDs)

By default, UTF-8 encoded files are tagged with CCSID 1208. To change this default to ISO8859-1 (CCSID 819):

  • Set the Git configuration globally:
git config --global core.utf8ccsid 819
  • Or set it for a specific repository:
git config core.utf8ccsid 819

Alternatively, set the environment variable GIT_UTF8_CCSID:

export GIT_UTF8_CCSID=819

Note: The GIT_UTF8_CCSID environment variable takes precedence over Git configuration settings.

Example: Setting the Default File Tag to ISO8859-1

# Set the UTF-8 file tag to CCSID 819
git config --global core.utf8ccsid 819
git clone https://github.com/git/git
cd git
ls -lT
# Files are now tagged with ISO8859-1

Handling Binary Files

To tag files as binary and prevent encoding conversion, use the binary attribute:

*.png binary

This ensures all *.png files are tagged as binary.

Managing Untagged Files

Git does not support adding untagged files. Use the open-source tagfile tool from zos-code-page-tools to tag files before adding them.

Specifying Multiple Encodings

You can specify multiple encoding attributes in .gitattributes. The last attribute listed takes precedence in case of conflicts.

Example:

* text zos-working-tree-encoding=IBM-1047
*.png binary

In this configuration:

  • All files except *.png are tagged as IBM-1047.
  • *.png files are tagged as binary.

Troubleshooting Common Issues

  • Issue: Git throws an error when adding files with mismatched encodings.
  • Solution: Ensure the file tag matches the working-tree-encoding. Use tagfile to adjust tags:
tagfile -q <directory>