encoding: rename internal string helpers and drop public to_bytes

Rename internal string encoders for clarity:
- maybe_string -> decode_string
- to_bytes -> encode_string

Keep the new filesystem-path helpers (decode_fs_path, encode_fs_path)
internal; use utils.encode_fs_path / utils.encode_string in __init__.py.

Remove pygit2.to_bytes from the public API; it was an undocumented
accidental public helper. Update changelog.

Assisted-by: Kimi K3

Author: jdavid

CHANGELOG.md

@@ -7,9 +7,8 @@
   `Config.__init__()`, and improve `Config` documentation
   [#1468](https://github.com/libgit2/pygit2/pull/1468)
 
-- Fix handling of non-UTF-8 file paths: add `decode_fs_path` and
-  `encode_fs_path`, use the filesystem codec for paths in `Repository.status()`,
-  `DiffFile.path`, index entries, checkout callbacks, and related APIs
+- Fix `UnicodeDecodeError` with non-UTF-8 file paths in `Repository.status()`,
+  `DiffFile.path`, index paths, checkout callbacks, and related APIs
   [#1451](https://github.com/libgit2/pygit2/issues/1451)
   [#1469](https://github.com/libgit2/pygit2/pull/1469)
 
@@ -42,6 +41,8 @@ Breaking changes:
 - Remove deprecated `Remote.ls_remotes(...)`, use `Remote.list_heads(...)`
   instead
 
+- Remove `pygit2.to_bytes`; it was an undocumented accidental public API
+
 
 # 1.19.3 (2026-06-13)
 

pygit2/__init__.py

@@ -31,7 +31,7 @@
 import typing
 
 # High level API
-from . import enums
+from . import enums, utils
 from ._build import __version__
 
 # Low level API
@@ -366,7 +366,7 @@
 from .settings import Settings
 from .submodules import Submodule
 from .transaction import ReferenceTransaction
-from .utils import decode_fs_path, encode_fs_path, to_bytes, to_str
+from .utils import to_str
 
 # Features
 features = enums.Feature(C.git_libgit2_features())
@@ -431,28 +431,28 @@ def init_repository(
     options.mode = mode
 
     if workdir_path:
-        workdir_path_ref = ffi.new('char []', encode_fs_path(workdir_path))
+        workdir_path_ref = ffi.new('char []', utils.encode_fs_path(workdir_path))
         options.workdir_path = workdir_path_ref
 
     if description:
-        description_ref = ffi.new('char []', to_bytes(description))
+        description_ref = ffi.new('char []', utils.encode_string(description))
         options.description = description_ref
 
     if template_path:
-        template_path_ref = ffi.new('char []', encode_fs_path(template_path))
+        template_path_ref = ffi.new('char []', utils.encode_fs_path(template_path))
         options.template_path = template_path_ref
 
     if initial_head:
-        initial_head_ref = ffi.new('char []', to_bytes(initial_head))
+        initial_head_ref = ffi.new('char []', utils.encode_string(initial_head))
         options.initial_head = initial_head_ref
 
     if origin_url:
-        origin_url_ref = ffi.new('char []', to_bytes(origin_url))
+        origin_url_ref = ffi.new('char []', utils.encode_string(origin_url))
         options.origin_url = origin_url_ref
 
     # Call
     crepository = ffi.new('git_repository **')
-    err = C.git_repository_init_ext(crepository, encode_fs_path(path), options)
+    err = C.git_repository_init_ext(crepository, utils.encode_fs_path(path), options)
     check_error(err)
 
     # Ok
@@ -531,13 +531,13 @@ def clone_repository(
         opts.fetch_opts.depth = depth
 
         if checkout_branch:
-            checkout_branch_ref = ffi.new('char []', to_bytes(checkout_branch))
+            checkout_branch_ref = ffi.new('char []', utils.encode_string(checkout_branch))
             opts.checkout_branch = checkout_branch_ref
 
         with git_fetch_options(payload, opts=opts.fetch_opts):
             with git_proxy_options(payload, opts.fetch_opts.proxy_opts, proxy):
                 crepo = ffi.new('git_repository **')
-                err = C.git_clone(crepo, to_bytes(url), encode_fs_path(path), opts)
+                err = C.git_clone(crepo, utils.encode_string(url), utils.encode_fs_path(path), opts)
                 payload.check_error(err)
 
     # Ok
@@ -560,7 +560,7 @@ def filter_unregister(name: str) -> None:
     if FilterList._is_filter_in_use(name):
         raise RuntimeError(f"filter still in use: '{name}'")
 
-    c_name = to_bytes(name)
+    c_name = utils.encode_string(name)
     err = C.git_filter_unregister(c_name)
     check_error(err)
 
@@ -934,7 +934,6 @@ def filter_unregister(name: str) -> None:
     'transaction',
     'ReferenceTransaction',
     'utils',
-    'to_bytes',
     'to_str',
     # __init__ module defined symbols
     'features',

pygit2/callbacks.py

@@ -77,10 +77,10 @@
 from .utils import (
     StrArray,
     decode_fs_path,
+    decode_string,
     encode_fs_path,
-    maybe_string,
+    encode_string,
     ptr_to_bytes,
-    to_bytes,
 )
 
 _Credentials = Username | UserPass | Keypair
@@ -460,7 +460,7 @@ def git_proxy_options(
     elif type(proxy) is str:
         opts.type = C.GIT_PROXY_SPECIFIED
         # Keep url in memory, otherwise memory is freed and bad things happen
-        payload.__proxy_url = ffi.new('char[]', to_bytes(proxy))  # type: ignore[union-attr]
+        payload.__proxy_url = ffi.new('char[]', encode_string(proxy))  # type: ignore[union-attr]
         opts.url = payload.__proxy_url  # type: ignore[union-attr]
     else:
         raise TypeError('Proxy must be None, True, or a string')
@@ -644,8 +644,8 @@ def _push_update_reference_cb(ref, msg, data):
     if not push_update_reference:
         return 0
 
-    refname = maybe_string(ref)
-    message = maybe_string(msg)
+    refname = decode_string(ref)
+    message = decode_string(msg)
     push_update_reference(refname, message)
     return 0
 
@@ -713,7 +713,7 @@ def _update_tips_cb(refname, a, b, data):
     if not update_tips:
         return 0
 
-    s = maybe_string(refname)
+    s = decode_string(refname)
     a = Oid(raw=bytes(ffi.buffer(a)[:]))
     b = Oid(raw=bytes(ffi.buffer(b)[:]))
     update_tips(s, a, b)
@@ -727,8 +727,8 @@ def _update_tips_cb(refname, a, b, data):
 
 def get_credentials(fn, url, username, allowed):
     """Call fn and return the credentials object."""
-    url_str = maybe_string(url)
-    username_str = maybe_string(username)
+    url_str = decode_string(url)
+    username_str = decode_string(username)
 
     creds = fn(url_str, username_str, allowed)
 
@@ -746,33 +746,33 @@ def get_credentials(fn, url, username, allowed):
     if cred_type == CredentialType.USERPASS_PLAINTEXT:
         name, passwd = credential_tuple
         err = C.git_credential_userpass_plaintext_new(
-            ccred, to_bytes(name), to_bytes(passwd)
+            ccred, encode_string(name), encode_string(passwd)
         )
 
     elif cred_type == CredentialType.SSH_KEY:
         name, pubkey, privkey, passphrase = credential_tuple
-        name = to_bytes(name)
+        name = encode_string(name)
         if pubkey is None and privkey is None:
             err = C.git_credential_ssh_key_from_agent(ccred, name)
         else:
             err = C.git_credential_ssh_key_new(
-                ccred, name, to_bytes(pubkey), to_bytes(privkey), to_bytes(passphrase)
+                ccred, name, encode_string(pubkey), encode_string(privkey), encode_string(passphrase)
             )
 
     elif cred_type == CredentialType.USERNAME:
         (name,) = credential_tuple
-        err = C.git_credential_username_new(ccred, to_bytes(name))
+        err = C.git_credential_username_new(ccred, encode_string(name))
 
     elif cred_type == CredentialType.SSH_MEMORY:
         name, pubkey, privkey, passphrase = credential_tuple
         if pubkey is None and privkey is None:
             raise TypeError('SSH keys from memory are empty')
         err = C.git_credential_ssh_key_memory_new(
             ccred,
-            to_bytes(name),
-            to_bytes(pubkey),
-            to_bytes(privkey),
-            to_bytes(passphrase),
+            encode_string(name),
+            encode_string(pubkey),
+            encode_string(privkey),
+            encode_string(passphrase),
         )
     else:
         raise TypeError('unsupported credential type')

pygit2/config.py

@@ -35,7 +35,7 @@
 # Import from pygit2
 from .errors import check_error
 from .ffi import C, ffi
-from .utils import encode_fs_path, to_bytes
+from .utils import encode_fs_path, encode_string
 
 if TYPE_CHECKING:
     from ._libgit2.ffi import GitConfigC, GitConfigEntryC
@@ -46,7 +46,7 @@ def str_to_bytes(value: str | bytes, name: str) -> bytes:
     if not isinstance(value, str):
         raise TypeError(f'{name} must be a string')
 
-    return to_bytes(value)
+    return encode_string(value)
 
 
 class ConfigIterator:
@@ -183,7 +183,7 @@ def __setitem__(self, key: str | bytes, value: bool | int | str | bytes) -> None
         elif isinstance(value, int):
             err = C.git_config_set_int64(self._config, key, value)
         else:
-            err = C.git_config_set_string(self._config, key, to_bytes(value))
+            err = C.git_config_set_string(self._config, key, encode_string(value))
 
         check_error(err)
 
@@ -215,7 +215,7 @@ def get_multivar(
         to filter the variables we're interested in.
         """
         name = str_to_bytes(name, 'name')
-        regex_bytes = to_bytes(regex or None)
+        regex_bytes = encode_string(regex or None)
 
         citer = ffi.new('git_config_iterator **')
         err = C.git_config_multivar_iterator_new(citer, self._config, name, regex_bytes)
@@ -305,15 +305,15 @@ def snapshot(self) -> 'Config':
     @staticmethod
     def parse_bool(text: str) -> bool:
         res = ffi.new('int *')
-        err = C.git_config_parse_bool(res, to_bytes(text))
+        err = C.git_config_parse_bool(res, encode_string(text))
         check_error(err)
 
         return res[0] != 0
 
     @staticmethod
     def parse_int(text: str) -> int:
         res = ffi.new('int64_t *')
-        err = C.git_config_parse_int64(res, to_bytes(text))
+        err = C.git_config_parse_int64(res, encode_string(text))
         check_error(err)
 
         return res[0]

pygit2/filter.py

@@ -32,7 +32,7 @@
 from ._pygit2 import Blob, FilterSource
 from .errors import check_error
 from .ffi import C, ffi
-from .utils import encode_fs_path, to_bytes
+from .utils import encode_fs_path, encode_string
 
 if TYPE_CHECKING:
     from ._libgit2.ffi import GitFilterListC
@@ -152,7 +152,7 @@ def _is_filter_in_use(cls, name: str) -> bool:
     def __contains__(self, name: str) -> bool:
         if not isinstance(name, str):
             raise TypeError('argument must be str')
-        c_name = to_bytes(name)
+        c_name = encode_string(name)
         result = C.git_filter_list_contains(self._pointer, c_name)
         return bool(result)
 

pygit2/options.py

@@ -34,7 +34,7 @@
 
 from .errors import check_error
 from .ffi import C, ffi
-from .utils import decode_fs_path, encode_fs_path, to_bytes, to_str
+from .utils import decode_fs_path, encode_fs_path, encode_string, to_str
 
 if TYPE_CHECKING:
     from ._libgit2.ffi import NULL_TYPE, ArrayC, char, char_pointer
@@ -520,7 +520,7 @@ def option(option_type: Option, arg1: Any = NOT_PASSED, arg2: Any = NOT_PASSED)
         check_args(option_type, arg1, arg2, 1)
 
         agent = arg1
-        agent_bytes = to_bytes(agent)
+        agent_bytes = encode_string(agent)
         agent_cdata = ffi.new('char[]', agent_bytes)
 
         err = C.git_libgit2_opts(option_type, agent_cdata)
@@ -531,7 +531,7 @@ def option(option_type: Option, arg1: Any = NOT_PASSED, arg2: Any = NOT_PASSED)
         check_args(option_type, arg1, arg2, 1)
 
         ciphers = arg1
-        ciphers_bytes = to_bytes(ciphers)
+        ciphers_bytes = encode_string(ciphers)
         ciphers_cdata = ffi.new('char[]', ciphers_bytes)
 
         err = C.git_libgit2_opts(option_type, ciphers_cdata)
@@ -669,7 +669,7 @@ def option(option_type: Option, arg1: Any = NOT_PASSED, arg2: Any = NOT_PASSED)
         ext_strings: list[ArrayC[char]] = []  # Keep references during the call
 
         for i, ext in enumerate(extensions):
-            ext_bytes = to_bytes(ext)
+            ext_bytes = encode_string(ext)
             ext_string: ArrayC[char] = ffi.new('char[]', ext_bytes)
             ext_strings.append(ext_string)
             ext_array[i] = ffi.cast('char *', ext_string)
@@ -781,7 +781,7 @@ def option(option_type: Option, arg1: Any = NOT_PASSED, arg2: Any = NOT_PASSED)
         check_args(option_type, arg1, arg2, 1)
 
         product = arg1
-        product_bytes = to_bytes(product)
+        product_bytes = encode_string(product)
         product_cdata = ffi.new('char[]', product_bytes)
 
         err = C.git_libgit2_opts(option_type, product_cdata)

pygit2/rebase.py

@@ -31,7 +31,7 @@
 from .errors import check_error
 from .ffi import C, ffi
 from .index import Index
-from .utils import maybe_string
+from .utils import decode_string
 
 if TYPE_CHECKING:
     from ._libgit2.ffi import GitRebaseC, GitRebaseOperationC
@@ -70,7 +70,7 @@ def __init__(self, type: RebaseOperationType, id: Oid, exec: 'str | None') -> No
     def _from_c(cls, coperation: 'GitRebaseOperationC') -> 'RebaseOperation':
         type = RebaseOperationType(coperation.type)
         id = Oid(raw=bytes(ffi.buffer(ffi.addressof(coperation, 'id'))[:]))
-        exec = maybe_string(coperation.exec)
+        exec = decode_string(coperation.exec)
         return cls(type, id, exec)
 
     def __repr__(self) -> str:
@@ -229,7 +229,7 @@ def abort(self) -> None:
     @property
     def orig_head_name(self) -> 'str | None':
         """The original HEAD ref name."""
-        return maybe_string(C.git_rebase_orig_head_name(self._rebase))
+        return decode_string(C.git_rebase_orig_head_name(self._rebase))
 
     @property
     def orig_head_id(self) -> Oid:
@@ -240,7 +240,7 @@ def orig_head_id(self) -> Oid:
     @property
     def onto_name(self) -> 'str | None':
         """The onto ref name."""
-        return maybe_string(C.git_rebase_onto_name(self._rebase))
+        return decode_string(C.git_rebase_onto_name(self._rebase))
 
     @property
     def onto_id(self) -> Oid:

pygit2/refspec.py

@@ -28,7 +28,7 @@
 # Import from pygit2
 from .errors import check_error
 from .ffi import C, ffi
-from .utils import to_bytes
+from .utils import encode_string
 
 
 class Refspec:
@@ -67,16 +67,16 @@ def src_matches(self, ref: str) -> bool:
         """Return True if the given string matches the source of this refspec,
         False otherwise.
         """
-        return bool(C.git_refspec_src_matches(self._refspec, to_bytes(ref)))
+        return bool(C.git_refspec_src_matches(self._refspec, encode_string(ref)))
 
     def dst_matches(self, ref: str) -> bool:
         """Return True if the given string matches the destination of this
         refspec, False otherwise."""
-        return bool(C.git_refspec_dst_matches(self._refspec, to_bytes(ref)))
+        return bool(C.git_refspec_dst_matches(self._refspec, encode_string(ref)))
 
     def _transform(self, ref: str, fn: Callable) -> str:
         buf = ffi.new('git_buf *', (ffi.NULL, 0))
-        err = fn(buf, self._refspec, to_bytes(ref))
+        err = fn(buf, self._refspec, encode_string(ref))
         check_error(err)
 
         try: