docs(api): document usage of head() methods

2 files changed, 32 insertions, 1 deletions

diff --git a/docs/api-usage.rst b/docs/api-usage.rst
index 2a8a3b9..d74814f 100644
--- a/docs/api-usage.rst
+++ b/docs/api-usage.rst
@@ -238,6 +238,28 @@ a project (the previous example used 2 API calls):
    project = gl.projects.get(1, lazy=True)  # no API call
    project.star()  # API call
 
+``head()`` methods
+========================
+
+All endpoints that support ``get()`` and ``list()`` also support a ``head()`` method.
+In this case, the server responds only with headers and not the response JSON or body.
+This allows more efficient API calls, such as checking repository file size without
+fetching its content.
+
+.. note::
+
+   In some cases, GitLab may omit specific headers. See more in the :ref:`pagination` section.
+
+.. code-block:: python
+
+   # See total number of personal access tokens for current user
+   gl.personal_access_tokens.head()
+   print(headers["X-Total"])
+
+   # See returned content-type for project GET endpoint
+   headers = gl.projects.head("gitlab-org/gitlab")
+   print(headers["Content-Type"])
+
 .. _pagination:
 
 Pagination
diff --git a/docs/gl_objects/projects.rst b/docs/gl_objects/projects.rst
index 82a7430..5b0e208 100644
--- a/docs/gl_objects/projects.rst
+++ b/docs/gl_objects/projects.rst
@@ -380,7 +380,16 @@ Get a file::
 
     # get the decoded content
     print(f.decode())
-    
+
+Get file details from headers, without fetching its entire content::
+
+    headers = project.files.head('README.rst', ref='main')
+
+    # Get the file size:
+    # For a full list of headers returned, see upstream documentation.
+    # https://docs.gitlab.com/ee/api/repository_files.html#get-file-from-repository
+    print(headers["X-Gitlab-Size"])
+
 Get a raw file::
     
     raw_content = project.files.raw(file_path='README.rst', ref='main')