### Initialize and Start Dulwich Git Server

Source: https://dulwich.readthedocs.io/en/latest/tutorial/remote

This snippet demonstrates how to initialize a Git repository, create a DictBackend for the server, and start a TCPGitServer in a separate thread using Dulwich. It sets up a local Git server for testing remote operations.

```Python
from dulwich.repo import Repo
from dulwich.server import DictBackend, TCPGitServer
import threading
repo = Repo.init("remote", mkdir=True)
cid = repo.do_commit(b"message", committer=b"Jelmer <jelmer@samba.org>")
backend = DictBackend({b'/': repo})
dul_server = TCPGitServer(backend, b'localhost', 0)
server_thread = threading.Thread(target=dul_server.serve)
server_thread.start()
server_address, server_port=dul_server.socket.getsockname()
```

--------------------------------

### Start Dulwich TCP Git Server

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/remote

Demonstrates how to initialize a Git repository, create a DictBackend for the server, and start a TCPGitServer in a separate thread using Dulwich. This sets up a local Git server for testing remote operations.

```python
from dulwich.repo import Repo
from dulwich.server import DictBackend, TCPGitServer
import threading
repo = Repo.init("remote", mkdir=True)
cid = repo.do_commit(b"message", committer=b"Jelmer <jelmer@samba.org>")
backend = DictBackend({b'/': repo})
dul_server = TCPGitServer(backend, b'localhost', 0)
server_thread = threading.Thread(target=dul_server.serve)
server_thread.start()
server_address, server_port=dul_server.socket.getsockname()
```

--------------------------------

### Creating a new Git repository with dulwich

Source: https://dulwich.readthedocs.io/en/latest/tutorial/repo

This example shows how to initialize a new Git repository using `dulwich.repo.Repo.init()`. It first creates a directory 'myrepo' and then initializes a new repository within it, mimicking the `git init` command.

```python
from os import mkdir
import sys
mkdir("myrepo")
repo = Repo.init("myrepo")
repo
```

--------------------------------

### Staging a new file in dulwich

Source: https://dulwich.readthedocs.io/en/latest/tutorial/repo

This example shows how to create a new file 'foo' within the repository and then stage it using `repo.stage()`. Staging prepares the file to be included in the next commit.

```python
f = open('myrepo/foo', 'wb')
_ = f.write(b"monty")
f.close()

repo.stage([b"foo"])
```

--------------------------------

### Install Dulwich Pure Python Version

Source: https://dulwich.readthedocs.io/en/latest/index

Commands to install Dulwich without its optional Rust performance bindings, ensuring a pure Python implementation. This can be done via `setup.py`, `pip install`, or specified in a `requirements.txt` file.

```Shell
python setup.py --pure install
```

```Shell
pip install --no-binary dulwich dulwich --config-settings "--build-option=--pure"
```

```Text
dulwich --config-settings "--build-option=--pure"
```

--------------------------------

### Opening the Git index with dulwich

Source: https://dulwich.readthedocs.io/en/latest/tutorial/repo

This example demonstrates how to access the Git index (staging area) of a repository using `repo.open_index()`. The index path is then printed, showing its location within the `.git` directory.

```python
index = repo.open_index()
print(index.path)
```

--------------------------------

### Create Dulwich TCP Git Client

Source: https://dulwich.readthedocs.io/en/latest/tutorial/remote

This code shows how to instantiate a TCPGitClient in Dulwich, connecting to a previously started TCPGitServer using its address and port. This client is used for interacting with remote Git repositories.

```Python
from dulwich.client import TCPGitClient
client = TCPGitClient(server_address, server_port)
```

--------------------------------

### Clone a Git repository using Dulwich Porcelain

Source: https://dulwich.readthedocs.io/en/latest/tutorial/porcelain

Shows how to clone a remote Git repository to a local directory. This includes examples for both anonymous cloning and cloning with basic authentication using username and password parameters.

```Python
porcelain.clone("git://github.com/jelmer/dulwich", "dulwich-clone")
```

```Python
porcelain.clone(
    "https://example.com/a-private-repo.git",
    "a-private-repo-clone",
    username="user", password="password")
```

--------------------------------

### Verify Dulwich Repository State with Git Shell Commands

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/object-store

Provides examples of shell commands (`git status`, `git checkout -f`, `cat spam`) to verify the state of a Git repository created and manipulated using Dulwich. These commands confirm that the Dulwich operations result in a standard, functional Git repository.

```Shell
$ cat spam
```

```Shell
$ git status
```

```Shell
$ git checkout -f
```

--------------------------------

### Push changes in a Dulwich repository

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/porcelain

Illustrates how to push committed changes from a source repository to a target repository using `dulwich.porcelain.push`. This example shows pushing the 'master' branch.

```python
tr = porcelain.init("targetrepo")
r = porcelain.push("testrepo", "targetrepo", "master")
```

--------------------------------

### Git Protocol pkt_line Format Example

Source: https://dulwich.readthedocs.io/en/latest/_sources/protocol

Demonstrates the structure of a Git pkt_line, which includes a 4-byte hexadecimal size prefix followed by the payload and a newline character. The size itself includes the 4 bytes of the prefix.

```Text
0009ABCD\n
```

--------------------------------

### Define `DummyGraphWalker` for Git Fetch

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/remote

Provides an example of a `DummyGraphWalker` class, a placeholder used in Dulwich's `fetch_pack` to simulate a client that doesn't have any existing Git objects. This ensures that all objects are fetched from the server.

```python
class DummyGraphWalker(object):
    def __init__(self):
        self.shallow = set()
    def ack(self, sha): pass
    def nak(self): pass
    def next(self): pass
    def __next__(self): pass
```

--------------------------------

### Shutdown Dulwich Git Server

Source: https://dulwich.readthedocs.io/en/latest/tutorial/remote

This simple snippet demonstrates how to gracefully shut down the TCPGitServer instance that was previously started, releasing its resources.

```Python
dul_server.shutdown()
```

--------------------------------

### Shutdown Dulwich TCP Git Server

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/remote

Illustrates how to gracefully shut down the `TCPGitServer` instance that was started earlier, releasing the network resources it was using.

```python
dul_server.shutdown()
```

--------------------------------

### Verify Fetched Pack File Header

Source: https://dulwich.readthedocs.io/en/latest/tutorial/remote

This code snippet checks the first four bytes of the fetched pack file to confirm it starts with the 'PACK' signature, indicating a valid Git pack file.

```Python
print(f.getvalue()[:4].decode('ascii'))
```

--------------------------------

### Creating a new commit with dulwich

Source: https://dulwich.readthedocs.io/en/latest/tutorial/repo

This example demonstrates how to create a new commit using `repo.do_commit()`. It requires a commit message and can optionally specify a committer. The function returns the SHA1 hash of the new commit.

```python
commit_id = repo.do_commit(
    b"The first commit", committer=b"Jelmer Vernooij <jelmer@samba.org>")
```

--------------------------------

### Define `determine_wants` Callback for Git Fetch

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/remote

Illustrates how to define a `determine_wants` callback function, which is used by Dulwich's `fetch_pack` method to specify which objects the client wants to retrieve from the Git server. This example retrieves all available objects.

```python
def determine_wants(refs, depth=None):
   # retrieve all objects
   return refs.values()
```

--------------------------------

### Define determine_wants Callback for Dulwich Fetch

Source: https://dulwich.readthedocs.io/en/latest/tutorial/remote

This Python function serves as a callback for `fetch_pack` in Dulwich, determining which objects the client wants to retrieve from the server. In this example, it's set to retrieve all available objects.

```Python
def determine_wants(refs, depth=None):
   # retrieve all objects
   return refs.values()
```

--------------------------------

### Initialize Git Repository with Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/object-store

Demonstrates how to initialize a new Git repository using the Dulwich library's `Repo.init` method. It creates a new directory for the repository if it doesn't exist, setting up the basic Git structure.

```Python
from dulwich.repo import Repo
repo = Repo.init("myrepo", mkdir=True)
```

--------------------------------

### Initialize a new Git repository using Dulwich Porcelain

Source: https://dulwich.readthedocs.io/en/latest/tutorial/porcelain

Demonstrates how to import the `dulwich.porcelain` module and initialize a new Git repository at a specified path. This creates the necessary Git directory structure.

```Python
from dulwich import porcelain
repo = porcelain.init("myrepo")
```

--------------------------------

### Creating a new Git repository with Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/repo

Shows how to create a new directory and initialize it as a Git repository using `Repo.init()`, similar to the `git init` command. This creates a non-bare repository with a `.git` folder.

```Python
from os import mkdir
import sys
mkdir("myrepo")
repo = Repo.init("myrepo")
repo
```

--------------------------------

### Initialize Dulwich Repository

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/tag

Initializes a new Git repository using Dulwich's `Repo` class, creating the directory if it doesn't exist. This sets up the basic structure for version control operations.

```Python
from dulwich.repo import Repo
_repo = Repo("myrepo", mkdir=True)
```

--------------------------------

### Opening an existing Git repository with Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/repo

Illustrates how to open an existing Git repository by passing its path to the `Repo` class constructor. This allows access to the repository's contents and operations for further manipulation.

```Python
repo = Repo("myrepo")
repo
```

--------------------------------

### Initialize Dulwich Git Repository

Source: https://dulwich.readthedocs.io/en/latest/tutorial/tag

This Python snippet initializes a new Git repository using `dulwich.repo.Repo`. It creates a directory named 'myrepo' and sets it up as a new Git repository, ready for further operations like adding commits and tags.

```Python
from dulwich.repo import Repo
_repo = Repo("myrepo", mkdir=True)
```

--------------------------------

### Initialize a new Dulwich Git repository

Source: https://dulwich.readthedocs.io/en/latest/tutorial/object-store

Demonstrates how to initialize a new Git repository using Dulwich's `Repo.init` function, creating the necessary directory structure for object storage.

```python
from dulwich.repo import Repo
repo = Repo.init("myrepo", mkdir=True)
```

--------------------------------

### Dulwich Index, Diff, and Walk Module APIs

Source: https://dulwich.readthedocs.io/en/latest/index

Documentation for new functions and classes related to Git index building, tree differencing, and object walking.

```APIDOC
dulwich.index.build_index_from_tree(repo: Repo, tree_id: str) -> Index
  - Purpose: Builds an index from a given tree object.
  - Note: New function introduced in 0.8.4.
```

```APIDOC
DeltaChainIterator
  - Purpose: Abstract class for quickly iterating all objects in a pack.
  - Implementations: Includes implementations for pack indexing and inflation (new in 0.8.0).
```

```APIDOC
walk.Walker
  - Purpose: Class for customizable commit walking.
  - Note: New module and class introduced in 0.8.0.
```

```APIDOC
diff_tree.tree_changes_for_merge(...) -> List[TreeChange]
  - Purpose: Function to detect tree changes specifically for merge operations.
  - Note: New function introduced in 0.8.0.
```

```APIDOC
RenameDetector
  - Purpose: Facilitates easy rename detection.
  - Behavior: Supports rename detection even without find_copies_harder (new in 0.8.0).
```

--------------------------------

### Initialize a new Dulwich repository

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/porcelain

Initializes a new Git repository at a specified path using `dulwich.porcelain.init`. The function can accept either a string path or a `Repo` object.

```python
from dulwich import porcelain

repo = porcelain.init("myrepo")
```

--------------------------------

### Opening an existing Git repository with dulwich

Source: https://dulwich.readthedocs.io/en/latest/tutorial/repo

This snippet illustrates how to open an existing Git repository by passing its path to the `dulwich.repo.Repo` constructor. This allows subsequent operations on the repository's contents.

```python
repo = Repo("myrepo")
repo
```

--------------------------------

### Importing Dulwich Repo object

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/repo

Demonstrates how to import the `Repo` class from the `dulwich.repo` module, which is the primary entry point for interacting with Git repositories in Dulwich.

```Python
from dulwich.repo import Repo
```

--------------------------------

### Access Git Commit Message using Dulwich Low-Level API

Source: https://dulwich.readthedocs.io/en/latest/index

Demonstrates how to use Dulwich's lower-level API to open a repository, get the HEAD commit hash, and retrieve the commit object and its message.

```Python
from dulwich.repo import Repo
r = Repo('.')
r.head()
c = r[r.head()]
c
c.message
```

--------------------------------

### Dulwich Repo Class API Methods

Source: https://dulwich.readthedocs.io/en/latest/index

Documentation for key methods of the Dulwich Repo class, including commit operations, configuration retrieval, and repository walking/cloning.

```APIDOC
Repo.do_commit(ref: Optional[str] = None, merge_heads: Optional[List[str]] = None, ...) -> Commit
  - Purpose: Performs a commit operation in the repository.
  - Behavior: Automatically uses user identity from .git/config or ~/.gitconfig if not explicitly specified (since 0.8.3).
  - Parameters:
    - ref: (New in 0.8.1) An optional reference to update.
    - merge_heads: (New in 0.8.1) Optional list of merge heads.
  - Returns: The created Commit object.
```

```APIDOC
Repo.get_config() -> Config
  - Purpose: Retrieves the repository's configuration.
  - Note: Support added for MemoryRepo.get_config (since 0.8.5).
```

```APIDOC
Repo.get_walker() -> Walker
  - Purpose: Returns a Walker object for customizable commit walking.
  - Note: New method introduced in 0.8.1. This method replaces the deprecated Repo.revision_history (deprecated in 0.8.0).
```

```APIDOC
Repo.clone(...) -> Repo
  - Purpose: Clones a repository.
  - Note: New method introduced in 0.8.1.
```

```APIDOC
Repo.revision_history(...) -> Iterator[Commit]
  - Purpose: Iterates through the revision history of the repository.
  - Note: Deprecated in 0.8.0 in favor of Repo.get_walker.
```

--------------------------------

### Dulwich Server and Utility APIs

Source: https://dulwich.readthedocs.io/en/latest/index

Documentation for server-side functionalities and general utilities within Dulwich.

```APIDOC
update_server_info(...) -> None
  - Purpose: Generates data for dumb server access.
  - Note: New method introduced in 0.8.2.
```

```APIDOC
WSGI Server
  - Purpose: Provides a WSGI interface for Git repositories.
  - Behavior: Now transparently handles when a git client submits data using Content-Encoding: gzip (since 0.8.4).
```

--------------------------------

### Dulwich Repository Initialization Format Argument

Source: https://dulwich.readthedocs.io/en/latest/index

Adds a `format` argument to `Repo.init()` and `Repo.init_bare()` methods, allowing specification of the repository format version (0 or 1). This sets the `core.repositoryformatversion` configuration value.

```APIDOC
dulwich.repo.Repo.init(path: Union[str, bytes, os.PathLike], format: int = 0) -> Repo
  - Initializes a new repository.
  - Parameters:
    - path: Path to the repository.
    - format: Repository format version (0 or 1). Sets `core.repositoryformatversion`.

dulwich.repo.Repo.init_bare(path: Union[str, bytes, os.PathLike], format: int = 0) -> Repo
  - Initializes a new bare repository.
  - Parameters:
    - path: Path to the bare repository.
    - format: Repository format version (0 or 1). Sets `core.repositoryformatversion`.
```

--------------------------------

### Dulwich Configuration and Indexing API Updates

Source: https://dulwich.readthedocs.io/en/latest/index

This section outlines changes to how Dulwich handles configuration settings, particularly `core.filemode`, and improvements to index building, including submodule support.

```APIDOC
dulwich.config.core.filemode
  - When the `core.filemode` configuration setting is false, file mode is now correctly ignored during index building.
  - The `core.filemode` setting is now initialized by probing the filesystem to determine trustable permissions, improving default behavior.

dulwich.config.parse_submodules(config_data)
  - A new function `parse_submodules` has been added to `dulwich.config` to parse submodule-related configuration data.

dulwich.index.build_index_from_tree(repo, tree, index=None)
  - Improved to correctly cope with submodules during the index building process.
```

--------------------------------

### Accessing the Git index in Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/repo

Demonstrates how to open the Git index (staging area) of a non-bare repository using `repo.open_index()`. The code then prints the index's file path and shows that a newly created index is initially empty.

```Python
index = repo.open_index()
print(index.path)
list(index)
```

--------------------------------

### Add and commit changes to a Dulwich repository

Source: https://dulwich.readthedocs.io/en/latest/tutorial/porcelain

Illustrates the process of initializing a repository, creating a new file, adding it to the staging area using `porcelain.add`, and then committing the changes with a specified commit message using `porcelain.commit`.

```Python
r = porcelain.init("testrepo")
open("testrepo/testfile", "w").write("data")
porcelain.add(r, "testfile")
porcelain.commit(r, b"A sample commit")
```

--------------------------------

### Dulwich Configuration and Miscellaneous API Changes

Source: https://dulwich.readthedocs.io/en/latest/index

Documentation for new configuration settings and other API updates across various modules.

```APIDOC
i18n.commitEncoding
  - Support added for this setting in config.
http.sslVerify and http.sslCAInfo
  - Support added for these configuration options.
dulwich.stash
  - Basic module added.
dulwich.archive.tar_stream
  - Supports a 'prefix' argument.
dulwich.mailmap
  - New file/module for reading mailmap files.
dulwich.archive
  - Sets the gzip header file modification time so that archives created from the same Git tree are always identical.
fastimport
  - Adds an 'extra' capability.
reflog
  - Starts writing entries.
tree_changes
  - Adds 'change_type_same' flag.
```

--------------------------------

### Staging files in a Dulwich Git repository

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/repo

Explains how to create a new file within the repository's working tree and then stage it using `repo.stage()`. The presence of the staged file in the index is subsequently verified.

```Python
f = open('myrepo/foo', 'wb')
_ = f.write(b"monty")
f.close()

repo.stage([b"foo"])
print(",".join([f.decode(sys.getfilesystemencoding()) for f in repo.open_index()]))
```

--------------------------------

### Implement DummyGraphWalker for Dulwich Fetch

Source: https://dulwich.readthedocs.io/en/latest/tutorial/remote

This class provides a placeholder 'graph walker' for Dulwich's `fetch_pack` method. It simulates a client that has no existing objects, ensuring all objects are sent by the server during a fetch operation.

```Python
class DummyGraphWalker(object):
    def __init__(self):
        self.shallow = set()
    def ack(self, sha): pass
    def nak(self): pass
    def next(self): pass
    def __next__(self): pass
```

--------------------------------

### Commit changes in a Dulwich repository

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/porcelain

Demonstrates the workflow for committing changes: initializing a repository, creating and adding a file, and then committing the changes with a commit message using `dulwich.porcelain.init`, `add`, and `commit`.

```python
r = porcelain.init("testrepo")
open("testrepo/testfile", "w").write("data")
porcelain.add(r, "testfile")
porcelain.commit(r, b"A sample commit")
```

--------------------------------

### Dulwich Porcelain Add Command Improvements

Source: https://dulwich.readthedocs.io/en/latest/index

Multiple improvements and fixes for `dulwich.porcelain.add()`: it now stages both untracked and modified files when no paths are specified (like `git add -A`); correctly handles symlinks pointing outside the repository; and fixes issues when adding the repository root or directories. Documentation for its default behavior has also been improved.

```APIDOC
dulwich.porcelain.add(paths: Optional[List[Union[str, bytes, os.PathLike]]] = None)
  - Stages files for commit.
  - Key improvements:
    - When `paths` is None: Stages both untracked and modified files (behaves like `git add -A`).
    - Symlink handling: Correctly adds symlinks pointing outside the repository.
    - Path handling: Correctly handles adding the repository root path or directories without corruption.
  - Documentation for default behavior has been improved.
```

--------------------------------

### Dulwich Transport and Client API

Source: https://dulwich.readthedocs.io/en/latest/index

Documentation for functions and classes related to Git transport mechanisms and client interactions, including HTTP and smart protocol support.

```APIDOC
get_transport_and_path(url: str, ...) -> Tuple[Transport, str]
  - Purpose: Determines the appropriate transport and path for a given Git URL.
  - Behavior:
    - Passes extra keyword arguments on to HttpGitClient (since 0.8.5).
    - Additional arguments are now passed on to the constructor of the transport (since 0.8.4).
  - Note: Fixes for HTTP/HTTPS URLs implemented in 0.8.2.
```

```APIDOC
HttpGitClient(...) -> HttpGitClient
  - Purpose: Client for interacting with Git smart servers over HTTP.
  - Behavior: Supports the smart server protocol over HTTP (new in 0.8.1). "Dumb" access is not yet supported.
```

```APIDOC
GitClient.send_pack(...) -> None
  - Purpose: Sends a pack file to a Git server.
  - Behavior: Now supports the 'side-band-64k' capability (since 0.8.1).
```

--------------------------------

### Dulwich Porcelain Module API Changes

Source: https://dulwich.readthedocs.io/en/latest/index

Documentation for new methods and fixes within the `dulwich.porcelain` module, which provides high-level Git operations.

```APIDOC
dulwich.porcelain.get_object_by_path
  - New method for easily accessing a path in another tree.
dulwich.porcelain.clone
  - Fixes support for custom transport arguments.
  - Fixes regression that prevented cloning of remote repositories.
  - Fixes handling of empty repositories.
dulwich.porcelain.describe
  - New method added.
dulwich.porcelain.ls_files
  - New method added.
dulwich.porcelain.fsck
  - Basic implementation added.
dulwich.porcelain.ls_tree
  - Fixes recursive option.
```

--------------------------------

### Dulwich Porcelain Move Command

Source: https://dulwich.readthedocs.io/en/latest/index

Introduces the `mv` command to `dulwich.porcelain` for moving files, providing functionality similar to `git mv`.

```APIDOC
dulwich.porcelain.mv(source: Union[str, bytes, os.PathLike], destination: Union[str, bytes, os.PathLike])
  - Moves files, similar to `git mv`.
```

--------------------------------

### MemoryRepo Description Management Methods

Source: https://dulwich.readthedocs.io/en/latest/index

New methods `set_description` and `get_description` have been implemented for the `MemoryRepo` class, allowing programmatic management of repository descriptions in memory. This provides more control and flexibility when working with in-memory Git repositories.

```APIDOC
MemoryRepo.set_description(description: str)
  - Sets the description for the in-memory repository.

MemoryRepo.get_description() -> str
  - Retrieves the description of the in-memory repository.
```

--------------------------------

### Create Git Tree and Add Blob Entry with Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/object-store

Illustrates how to create a Git tree object and add an entry to it. The entry links a filename ('spam'), file mode (0o100644 for a regular file), and the SHA-1 ID of a previously created blob, representing a file within a directory structure.

```Python
from dulwich.objects import Tree
tree = Tree()
tree.add(b"spam", 0o100644, blob.id)
```

--------------------------------

### Dulwich Object Store and Client API Improvements

Source: https://dulwich.readthedocs.io/en/latest/index

Improvements to object store and client functionalities, including `GitClient.fetch_pack` returning symrefs, a new method for incrementally committing changes to a tree structure, and a basic repack method for pack-based object stores. These changes enhance the library's capabilities for low-level Git object manipulation and client-server interactions.

```APIDOC
GitClient.fetch_pack(...)
  - Now returns symrefs (symbolic references).

dulwich.object_store.commit_tree_changes(tree_id, changes)
  - New method to incrementally commit changes to a tree structure.

PackBasedObjectStore.repack()
  - Basic method to repack the object store.
```

--------------------------------

### Verifying staged files in dulwich index

Source: https://dulwich.readthedocs.io/en/latest/tutorial/repo

This snippet verifies that the previously staged file 'foo' is now present in the repository's index. It opens the index, decodes the file paths, and prints them to confirm staging.

```python
print(",".join([f.decode(sys.getfilesystemencoding()) for f in repo.open_index()]))
```

--------------------------------

### Dulwich API PathLike Object Support

Source: https://dulwich.readthedocs.io/en/latest/index

Adds comprehensive support for `os.PathLike` objects (e.g., `pathlib.Path`) across the Dulwich API. Functions accepting file paths now support these objects in addition to strings and bytes, covering repository operations, configuration, ignore files, and major entry points.

```APIDOC
# General API Improvement: os.PathLike Support
All Dulwich API functions that accept file paths now support:
  - `str`
  - `bytes`
  - `os.PathLike` (e.g., `pathlib.Path` objects).
This applies to repository operations, configuration file handling, ignore file processing, and major entry points.
```

--------------------------------

### Creating a new commit in Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/repo

Shows how to create a new commit from staged changes using `Repo.do_commit()`. It demonstrates specifying a commit message and committer, and verifies that the repository's head now points to the new commit's SHA1.

```Python
commit_id = repo.do_commit(
    b"The first commit", committer=b"Jelmer Vernooij <jelmer@samba.org>")
repo.head() == commit_id
```

--------------------------------

### Clone a Dulwich repository

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/porcelain

Clones a Git repository from a source URL to a destination path using `dulwich.porcelain.clone`. It supports basic authentication by providing `username` and `password` parameters for private repositories.

```python
porcelain.clone("git://github.com/jelmer/dulwich", "dulwich-clone")
```

```python
porcelain.clone(
    "https://example.com/a-private-repo.git",
    "a-private-repo-clone",
    username="user", password="password")
```

--------------------------------

### Fetch Raw Pack File using Dulwich Client

Source: https://dulwich.readthedocs.io/en/latest/tutorial/remote

This snippet demonstrates how to use the Dulwich TCPGitClient to fetch a raw Git pack file. It utilizes the `determine_wants` callback and `DummyGraphWalker` to control the fetch process and writes the received data to a BytesIO object.

```Python
from io import BytesIO
f = BytesIO()
result = client.fetch_pack(b"/", determine_wants,
   DummyGraphWalker(), pack_data=f.write)
```

--------------------------------

### Dulwich Porcelain Commands: Additions and Enhancements

Source: https://dulwich.readthedocs.io/en/latest/index

This section details new and improved commands within the `dulwich.porcelain` module. It includes a new command for updating the head, a command to check ignore rules, and enhancements to `status` and `add` commands to support ignore files and relative paths. A basic `dulwich pull` command is also introduced, enhancing the library's high-level Git operations.

```APIDOC
dulwich.porcelain.update_head()
  - Adds a new command to update the repository's head.

dulwich.porcelain.check_ignore()
  - New command to check ignore rules.

dulwich.porcelain.status(ignored: bool = False)
  - Now supports an 'ignored' argument to include ignored files.
  - Honors ignore files (e.g., .gitignore).

dulwich.porcelain.add(files: list[str], ...)
  - Honors ignore files.
  - Allows passing in relative paths (previously raised exception for absolute paths in Repo.stage()).

dulwich pull
  - Basic command for pulling changes from a remote.
  - Copes with existing submodules during pull.
```

--------------------------------

### Fetch Raw Git Pack File using Dulwich Client

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/remote

Demonstrates how to use the Dulwich `TCPGitClient`'s `fetch_pack` method to retrieve a raw Git pack file. It specifies the `determine_wants` callback and a `DummyGraphWalker`, writing the received data to a `BytesIO` object for inspection.

```python
from io import BytesIO
f = BytesIO()
result = client.fetch_pack(b"/", determine_wants,
   DummyGraphWalker(), pack_data=f.write)

print(f.getvalue()[:4].decode('ascii'))
```

--------------------------------

### Git Protocol: git-upload-pack

Source: https://dulwich.readthedocs.io/en/latest/protocol

Details the `git-upload-pack` protocol used by Git commands like `git-ls-remote`, `git-clone`, `git-fetch`, and `git-pull`. It outlines the client-server interaction for fetching objects, including capability negotiation, ref advertisement, SHA1 negotiation, and pack transfer.

```APIDOC
git-upload-pack Protocol:
  Purpose: Used for fetching objects (git-ls-remote, git-clone, git-fetch, git-pull).
  Client: Typically git-fetch-pack
  Server: git-upload-pack

  Capabilities: multi_ack, thin-pack, ofs-delta, sideband, sideband-64k
    - thin-pack: Can reference objects not in the current pack.

  Flow:
    1. Server tells client what refs it has.
    2. Client states which SHA1s it wants.
    3. Client reports which SHA1s it has.
    4. Server ACKs client's SHA1s, allowing client to stop sending.
    5. Server calculates optimal pack and sends it to the client.
```

--------------------------------

### Verify Git HEAD Reference with Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/object-store

Demonstrates how to access and verify the Git HEAD reference using Dulwich. It checks if HEAD points to the initial commit and if it matches the master branch reference, confirming the repository's current state.

```Python
head = repo.refs[b'HEAD']
head == commit.id
True
head == repo.refs[b'refs/heads/master']
True
```

--------------------------------

### Dulwich Repository and Reference Management API

Source: https://dulwich.readthedocs.io/en/latest/index

This section covers API changes related to repository objects, reference containers, and general repository management, including context manager support for `Repo` and new methods for reference handling.

```APIDOC
dulwich.repo.Repo(path, bare=False)
  - The `Repo` class now implements the context manager protocol, allowing it to be used with Python's `with` statement for automatic resource management.
  - Example Usage:
    with Repo('/path/to/repo') as repo:
        # Perform operations on repo
        pass

dulwich.refs.RefsContainer.follow(ref_name)
  - A new `follow` method has been added to `RefsContainer` objects, allowing traversal of symbolic references.

dulwich.client.LocalGitClient.fetch_pack(repo, refs, progress=None)
  - The `fetch_pack` method now consistently returns remote references, aligning with its documented behavior.

dulwich.objects.Commit.tree
  - Corrected handling when `Commit.tree` is assigned an actual `Tree` object directly, rather than just its ID.

dulwich.worktree
  - Added comprehensive support for Git worktrees, aligning with `git-worktree(1)` functionality.

dulwich.repo (internal)
  - Added support for the `commondir` file within Git control directories, improving compatibility with various Git repository layouts.
```

--------------------------------

### Git Protocol: git-receive-pack

Source: https://dulwich.readthedocs.io/en/latest/protocol

Describes the `git-receive-pack` protocol, primarily used by `git push` for receiving objects and updates. It covers the client-server interaction for pushing changes and supported capabilities.

```APIDOC
git-receive-pack Protocol:
  Purpose: Used for pushing objects and updates (git push).
  Client: Typically git-send-pack
  Server: git-receive-pack

  Capabilities: report-status, delete-ref
```

--------------------------------

### Create Git Blob from String with Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/object-store

Shows how to create a Git blob object from a string of content using `Blob.from_string`. It also demonstrates how to retrieve and print the SHA-1 ID of the created blob, which uniquely identifies its content.

```Python
from dulwich.objects import Blob
blob = Blob.from_string(b"My file content\n")
print(blob.id.decode('ascii'))
```

--------------------------------

### Create Dulwich TCP Git Client

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/remote

Shows how to construct a `TCPGitClient` instance in Dulwich to interact with a remote Git server, using the previously obtained server address and port. This client is essential for performing remote Git operations.

```python
from dulwich.client import TCPGitClient
client = TCPGitClient(server_address, server_port)
```

--------------------------------

### Git Protocol: git-receive-pack

Source: https://dulwich.readthedocs.io/en/latest/_sources/protocol

Describes the `git-receive-pack` protocol, primarily used by `git push`. It outlines the client-server interaction for pushing changes, including supported capabilities like `report-status` and `delete-ref`.

```APIDOC
git-receive-pack
  - Used by: git push
  - Client connects local git-send-pack to remote git-receive-pack.
  - Capabilities:
    - report-status
    - delete-ref
```

--------------------------------

### Git Protocol: git-upload-pack

Source: https://dulwich.readthedocs.io/en/latest/_sources/protocol

Details the `git-upload-pack` protocol used by `git-ls-remote`, `git-clone`, `git-fetch`, and `git-pull`. It describes the client-server interaction for fetching objects, including capability negotiation and the process of the server reporting refs, client requesting SHAs, and the server sending an optimal pack.

```APIDOC
git-upload-pack
  - Used by: git-ls-remote, git-clone, git-fetch, git-pull
  - Client connects local git-fetch-pack to remote git-upload-pack.
  - Capabilities:
    - multi_ack
    - thin-pack: Can reference objects not in the current pack.
    - ofs-delta
    - sideband
    - sideband-64k
  - Protocol Flow:
    1. Server tells client what refs it has.
    2. Client states which SHA1s it would like.
    3. Client starts reporting which SHA1s it has.
    4. Server ACKs these, allowing client to stop sending SHA1s.
    5. Server calculates and sends optimal pack to client.
```

--------------------------------

### Create Git Branch Reference with Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/object-store

Shows how to create a branch reference in the Dulwich repository. It sets the 'refs/heads/master' reference to point to the SHA-1 ID of the initial commit, establishing the master branch.

```Python
repo.refs[b'refs/heads/master'] = commit.id
```

--------------------------------

### Create Git Commit Object with Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/object-store

Details the process of constructing a Git commit object. It sets the commit's tree ID, author/committer information, timestamps, timezone, encoding, and commit message. This initial commit has no parents.

```Python
from dulwich.objects import Commit, parse_timezone
from time import time
commit = Commit()
commit.tree = tree.id
author = b"Your Name <your.email@example.com>"
commit.author = commit.committer = author
commit.commit_time = commit.author_time = int(time())
tz = parse_timezone(b'-0200')[0]
commit.commit_timezone = commit.author_timezone = tz
commit.encoding = b"UTF-8"
commit.message = b"Initial commit"
```

--------------------------------

### Dulwich Index and Repo Class API Changes

Source: https://dulwich.readthedocs.io/en/latest/index

Documentation for changes and new methods in the `Index` and `Repo` classes, affecting object and repository management.

```APIDOC
Index.items
  - New method added.
Index.iterblobs
  - Deprecated. Renamed to Index.iterobjects.
Index.iterobjects
  - New name for Index.iterblobs.
Repo.clone
  - Adds 'checkout' argument.
Repo.get_shallow
  - New method added.
Repo.do_commit()
  - Now raises an exception when passing invalid author/committer values.
```

--------------------------------

### Dulwich Protocol and Server API Changes

Source: https://dulwich.readthedocs.io/en/latest/index

Details updates to the Dulwich protocol and server-side handling, including new methods for protocol interaction and optional request passing.

```APIDOC
Protocol.eof():
  - New method added.

Protocol.unread_pkt_line():
  - New method added.

Server handlers:
  - Can optionally receive a request object.
```

--------------------------------

### Dulwich Client and Transport API Changes

Source: https://dulwich.readthedocs.io/en/latest/index

Documentation for updates to client and transport mechanisms, including SSH and HTTP handling.

```APIDOC
dulwich.client.parse_rsync_url
  - New function factored out.
dulwich.client.PLinkSSHVendor
  - New class for creating connections using PuTTY’s plink.exe.
SSHVendor implementations
  - Only pass 'key_filename' and 'password' if set (helps older implementations).
  - Supports password and keyfile ssh options.
dulwich.client.HttpGitClient
  - 'opener' argument (urllib2 opener instance) replaced by 'pool_manager' argument (urllib3 pool manager instance).
  - Fixes repeat HTTP requests using the same smart HTTP client.
GitClient.send_pack
  - Now accepts a 'generate_pack_data' rather than a 'generate_pack_contents' function for performance reasons.
```

--------------------------------

### Generate and Print Git Tree Diff using Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/object-store

This snippet demonstrates how to use `dulwich.patch.write_tree_diff` to generate a diff between two Git trees. It writes the diff output to a `BytesIO` object and then decodes and prints it to standard output, showcasing the changes between the old and new tree states.

```Python
from dulwich.patch import write_tree_diff
from io import BytesIO
out = BytesIO()
write_tree_diff(out, repo.object_store, commit.tree, tree.id)
import sys; _ = sys.stdout.write(out.getvalue().decode('ascii'))
```

--------------------------------

### Fetch Git Objects into Local Dulwich Repository

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/remote

Shows how to fetch objects from a remote Git repository into a newly initialized local Dulwich repository using the `client.fetch` method. Dulwich automatically handles the graph walking and importing of the received pack file.

```python
from dulwich.repo import Repo
local = Repo.init("local", mkdir=True)
remote_refs = client.fetch(b"/", local)
local.close()
```

--------------------------------

### Importing the dulwich Repo object

Source: https://dulwich.readthedocs.io/en/latest/tutorial/repo

This snippet demonstrates how to import the `Repo` class from the `dulwich.repo` module. The `Repo` object is the primary interface for interacting with Git repositories in `dulwich`.

```python
from dulwich.repo import Repo
```

--------------------------------

### Create and Store Commit Object in Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/tag

Demonstrates how to construct a `Commit` object, including its associated `Blob` and `Tree` objects, and add them to the repository's object store. This process involves defining author, time, message, and linking the commit to a tree. It also sets the master branch reference to this new commit.

```Python
from dulwich.objects import Blob, Tree, Commit, parse_timezone
permissions = 0100644
author = "John Smith"
blob = Blob.from_string("empty")
tree = Tree()
tree.add(tag, permissions, blob.id)
commit = Commit()
commit.tree = tree.id
commit.author = commit.committer = author
commit.commit_time = commit.author_time = int(time())
tz = parse_timezone('-0200')[0]
commit.commit_timezone = commit.author_timezone = tz
commit.encoding = "UTF-8"
commit.message = 'Tagging repo: ' + message

object_store = _repo.object_store
object_store.add_object(blob)
object_store.add_object(tree)
object_store.add_object(commit)
master_branch = 'master'
_repo.refs['refs/heads/' + master_branch] = commit.id
```

--------------------------------

### Dulwich Porcelain Module API Changes

Source: https://dulwich.readthedocs.io/en/latest/index

This section details various improvements and fixes to the `dulwich.porcelain` module, which provides high-level Git commands. Changes include new functionalities, enhanced argument handling, and Python 3 compatibility fixes for common Git operations like cloning, resetting, listing remotes, pulling, pushing, and managing unstaged changes.

```APIDOC
dulwich.porcelain.remote_add(repo, name, url)
  - Adds a new remote to the specified repository.

dulwich.porcelain.clone(source, target, bare=False, checkout=True, depth=None, recurse_submodules=False, branch=None, no_checkout=False, no_hardlinks=False, config=None, progress=None)
  - Allows cloning a repository even if it lacks a HEAD reference.
  - Correctly adds the remote repository after cloning.
  - Properly pulls in tags during the cloning process.

dulwich.porcelain.reset(repo, committish, mode='soft')
  - The `reset` function now correctly respects the `committish` argument, allowing precise control over the reset target.

dulwich.porcelain.ls_remote(url, heads=True, tags=True, upload_pack=None, protocol_version=None, progress=None)
  - Fixed compatibility issues and improved functionality on Python 3.

dulwich.porcelain.get_unstaged_changes(repo, tree=None, index=None, ignore_untracked=False)
  - Enhanced to correctly handle deleted files when determining unstaged changes.

dulwich.porcelain.pull(repo, remote_name='origin', branch=None, refspecs=None, progress=None)
  - Fixed compatibility issues and improved functionality on Python 3.

dulwich.porcelain.ls_tree(repo, treeish, path=None, recursive=False, long=False)
  - New implementation added to list the contents of a tree object.

dulwich.porcelain.push(repo, remote_name='origin', refspecs=None, force=False, progress=None)
  - Fixed a regression that caused untouched references to be removed during SSH pushes.
  - Now supports explicitly removing references during a push operation.
```

--------------------------------

### Dulwich Git Smart Server Protocol Operations

Source: https://dulwich.readthedocs.io/en/latest/tutorial/remote

Overview of the three basic operations provided by the Git smart server protocol, accessible over TCP, SSH, or HTTP, which facilitate communication between Git clients and servers.

```APIDOC
upload-pack:
  Description: Provides a pack with objects requested by the client.
  Protocol: Git smart server protocol
  Access: TCP (git://), SSH (git+ssh://), HTTP (http://)

receive-pack:
  Description: Imports a pack with objects provided by the client.
  Protocol: Git smart server protocol
  Access: TCP (git://), SSH (git+ssh://), HTTP (http://)

upload-archive:
  Description: Provides a tarball with the contents of a specific revision.
  Protocol: Git smart server protocol
  Access: TCP (git://), SSH (git+ssh://), HTTP (http://)
```

--------------------------------

### Dulwich Porcelain and Object Store Pruning

Source: https://dulwich.readthedocs.io/en/latest/index

Introduces a `prune` method for object stores to clean orphaned temporary pack files, now integrated with `garbage_collect()`. A `prune` command is also added to `dulwich.porcelain` for CLI usage.

```APIDOC
dulwich.object_store.ObjectStore.prune()
  - Cleans up orphaned temporary pack files.
  - Called by `garbage_collect()`.

dulwich.porcelain.prune()
  - CLI command for pruning.
```

--------------------------------

### Git Smart Server Protocol Operations

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/remote

Describes the core operations supported by the Git smart server protocol, including `upload-pack`, `receive-pack`, and `upload-archive`, and the transport protocols supported by Dulwich for accessing remote repositories.

```APIDOC
Git Smart Server Protocol Operations:

*   upload-pack:
    -   Provides a pack with objects requested by the client.

*   receive-pack:
    -   Imports a pack with objects provided by the client.

*   upload-archive:
    -   Provides a tarball with the contents of a specific revision.

Transport Protocols:
*   plain TCP (git://)
*   SSH (git+ssh://)
*   tunneled over HTTP (http://)
```

--------------------------------

### Create Subsequent Git Commit Object with Dulwich

Source: https://dulwich.readthedocs.io/en/latest/_sources/tutorial/object-store

Shows how to create a second Git commit object, linking it to the updated tree and specifying its parent as the previous commit. This establishes the commit history, including author/committer details and timestamps for the new commit.

```Python
from dulwich.objects import Commit
from time import time
c2 = Commit()
c2.tree = tree.id
c2.parents = [commit.id]
c2.author = c2.committer = b"John Doe <john@example.com>"
c2.commit_time = c2.author_time = int(time())
c2.commit_timezone = c2.author_timezone = 0
c2.encoding = b"UTF-8"
```

--------------------------------

### Define a Git commit object using Dulwich

Source: https://dulwich.readthedocs.io/en/latest/tutorial/object-store

Details the process of instantiating a `Commit` object in Dulwich, setting its tree, author, committer, timestamps, timezone, encoding, and message. This prepares the commit for storage, linking it to a specific tree state.

```python
from dulwich.objects import Commit, parse_timezone
from time import time
commit = Commit()
commit.tree = tree.id
author = b"Your Name <your.email@example.com>"
commit.author = commit.committer = author
commit.commit_time = commit.author_time = int(time())
tz = parse_timezone(b'-0200')[0]
commit.commit_timezone = commit.author_timezone = tz
commit.encoding = b"UTF-8"
commit.message = b"Initial commit"
```

--------------------------------

### Create a Git blob from string content using Dulwich

Source: https://dulwich.readthedocs.io/en/latest/tutorial/object-store

Shows how to create a Git blob object from a byte string using `dulwich.objects.Blob.from_string` and print its SHA-1 ID. Blobs represent file content in Git.

```python
from dulwich.objects import Blob
blob = Blob.from_string(b"My file content\n")
print(blob.id.decode('ascii'))
```

--------------------------------

### Push changes from a Dulwich repository to a target repository

Source: https://dulwich.readthedocs.io/en/latest/tutorial/porcelain

Demonstrates how to push committed changes from a source repository (e.g., 'testrepo') to a target repository (e.g., 'targetrepo') using `porcelain.push`, specifying the branch to push (e.g., 'master').

```Python
tr = porcelain.init("targetrepo")
r = porcelain.push("testrepo", "targetrepo", "master")
```