diff --git a/CHANGELOG.md b/CHANGELOG.md
index e66bfddb..57563fce 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,7 +33,7 @@
 
 ## `bat` as a library
 
-- Deprecate `HighlightingAssets::syntaxes()` and `HighlightingAssets::syntax_for_file_name()`. Use `HighlightingAssets::get_syntaxes()` and `HighlightingAssets::get_syntax_for_file_name()` instead. They return a `Result` which is needed for upcoming lazy-loading work to improve startup performance. They also return what `SyntaxSet` the returned `SyntaxReference` belongs to. See #1747, #1755 and #1776 (@Enselic)
+- Deprecate `HighlightingAssets::syntaxes()` and `HighlightingAssets::syntax_for_file_name()`. Use `HighlightingAssets::get_syntaxes()` and `HighlightingAssets::get_syntax_for_path()` instead. They return a `Result` which is needed for upcoming lazy-loading work to improve startup performance. They also return which `SyntaxSet` the returned `SyntaxReference` belongs to. See #1747, #1755, #1776, #1862 (@Enselic)
 - Remove `HighlightingAssets::from_files` and `HighlightingAssets::save_to_cache`. Instead of calling the former and then the latter you now make a single call to `bat::assets::build`. See #1802 (@Enselic)
 - Replace  the `error::Error(error::ErrorKind, _)` struct and enum with an `error::Error` enum. `Error(ErrorKind::UnknownSyntax, _)` becomes `Error::UnknownSyntax`, etc. Also remove the `error::ResultExt` trait. These changes stem from replacing `error-chain` with `thiserror`. See #1820 (@Enselic)
 
diff --git a/src/assets.rs b/src/assets.rs
index 8eb1fe49..1c820d6c 100644
--- a/src/assets.rs
+++ b/src/assets.rs
@@ -140,29 +140,38 @@ impl HighlightingAssets {
         }
     }
 
-    /// Use [Self::get_syntax_for_file_name] instead
+    /// Use [Self::get_syntax_for_path] instead
     #[deprecated]
     pub fn syntax_for_file_name(
         &self,
         file_name: impl AsRef<Path>,
         mapping: &SyntaxMapping,
     ) -> Option<&SyntaxReference> {
-        self.get_syntax_for_file_name(file_name, mapping)
-            .expect(
-                ".syntax_for_file_name() is deprecated, use .get_syntax_for_file_name() instead",
-            )
+        self.get_syntax_for_path(file_name, mapping)
+            .ok()
             .map(|syntax_in_set| syntax_in_set.syntax)
     }
 
-    pub fn get_syntax_for_file_name(
-        &self,
-        file_name: impl AsRef<Path>,
-        mapping: &SyntaxMapping,
-    ) -> Result<Option<SyntaxReferenceInSet>> {
-        Ok(self.get_syntax_for_path(file_name.as_ref(), mapping).ok())
-    }
-
-    fn get_syntax_for_path(
+    /// Detect the syntax based on, in order:
+    ///  1. Syntax mappings (e.g. `/etc/profile` -> `Bourne Again Shell (bash)`)
+    ///  2. The file name (e.g. `Dockerfile`)
+    ///  3. The file name extension (e.g. `.rs`)
+    ///
+    /// When detecting syntax based on syntax mappings, the full path is taken
+    /// into account. When detecting syntax based on file name, no regard is
+    /// taken to the path of the file. Only the file name itself matters. When
+    /// detecting syntax based on file name extension, only the file name
+    /// extension itself matters.
+    ///
+    /// Returns [Error::UndetectedSyntax] if it was not possible detect syntax
+    /// based on path/file name/extension (or if the path was mapped to
+    /// [MappingTarget::MapToUnknown]). In this case it is appropriate to fall
+    /// back to other methods to detect syntax. Such as using the contents of
+    /// the first line of the file.
+    ///
+    /// Returns [Error::UnknownSyntax] if a syntax mapping exist, but the mapped
+    /// syntax does not exist.
+    pub fn get_syntax_for_path(
         &self,
         path: impl AsRef<Path>,
         mapping: &SyntaxMapping,
@@ -218,7 +227,6 @@ impl HighlightingAssets {
 
         let path = input.path();
         let path_syntax = if let Some(path) = path {
-            // If a path was provided, we try and detect the syntax based on extension mappings.
             self.get_syntax_for_path(
                 PathAbs::new(path).map_or_else(|_| path.to_owned(), |p| p.as_path().to_path_buf()),
                 mapping,
diff --git a/src/bin/bat/main.rs b/src/bin/bat/main.rs
index 735c0b2b..1f4f6e37 100644
--- a/src/bin/bat/main.rs
+++ b/src/bin/bat/main.rs
@@ -104,10 +104,8 @@ pub fn get_languages(config: &Config) -> Result<String> {
             }
 
             let test_file = Path::new("test").with_extension(extension);
-            let syntax_in_set = assets
-                .get_syntax_for_file_name(test_file, &config.syntax_mapping)
-                .unwrap(); // safe since .get_syntaxes() above worked
-            matches!(syntax_in_set, Some(syntax_in_set) if syntax_in_set.syntax.name == lang_name)
+            let syntax_in_set = assets.get_syntax_for_path(test_file, &config.syntax_mapping);
+            matches!(syntax_in_set, Ok(syntax_in_set) if syntax_in_set.syntax.name == lang_name)
         });
     }