diff --git a/app/ghcup/GHCup/OptParse/Compile.hs b/app/ghcup/GHCup/OptParse/Compile.hs
index efcefad..82df4d1 100644
--- a/app/ghcup/GHCup/OptParse/Compile.hs
+++ b/app/ghcup/GHCup/OptParse/Compile.hs
@@ -154,9 +154,7 @@ Examples:
 
 Examples:
   # compile 1.7.0.0 from hackage for 8.10.7, running 'cabal update' before the build
-  ghcup compile hls --hackage-version 1.7.0.0 --ghc 8.10.7 --cabal-update
-  # compile 1.7.0.0 from official source dist for ghc 8.10.5 and 8.10.7, passing '--allow-newer' to cabal
-  ghcup compile hls -v 1.7.0.0 -j 12 --ghc 8.10.5 --ghc 8.10.7 -- --allow-newer
+  ghcup compile hls --version 1.7.0.0 --ghc 8.10.7 --cabal-update
   # compile from master for ghc 9.2.3 using 'git describe' to name the binary and ignore the pinned index state
   ghcup compile hls -g master --git-describe-version --ghc 9.2.3 -- --index-state=@(date '+%s')
   # compile a specific commit for ghc 9.2.3 and set a specifc version for the binary name
@@ -287,12 +285,12 @@ ghcCompileOpts =
 hlsCompileOpts :: Parser HLSCompileOptions
 hlsCompileOpts =
   HLSCompileOptions
-    <$> ((HLS.SourceDist <$> option
+    <$> ((HLS.HackageDist <$> option
           (eitherReader
             (first (const "Not a valid version") . version . T.pack)
           )
           (short 'v' <> long "version" <> metavar "VERSION" <> help
-            "The tool version to compile"
+            "The version to compile (pulled from hackage)"
             <> (completer $ versionCompleter Nothing HLS)
           )
           )
@@ -307,12 +305,12 @@ hlsCompileOpts =
           ))
           ))
           <|>
-          (HLS.HackageDist <$> (option
+          (HLS.SourceDist <$> (option
             (eitherReader
               (first (const "Not a valid version") . version . T.pack)
             )
-          (long "hackage-version" <> metavar "HACKAGE_VERSION" <> help
-            "The hackage version to compile"
+          (long "source-dist" <> metavar "VERSION" <> help
+            "The version to compile (pulled from packaged git sources)"
             <> (completer $ versionCompleter Nothing HLS)
           )
           ))
diff --git a/docs/guide.md b/docs/guide.md
index 0b15fa5..3f3bd40 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -202,7 +202,9 @@ and produce the binaries `ghc-8.10.2-eff` and `ghc-head` respectively.
 GHCup always needs to know which version the bindist corresponds to (this is not automatically
 detected).
 
-## Compiling GHC from source
+## Compiling from source
+
+### GHC
 
 Compiling from source is supported for both source tarballs and arbitrary git refs. See `ghcup compile ghc --help`
 for a list of all available options.
@@ -214,6 +216,45 @@ Common `build.mk` options are explained [here](https://gitlab.haskell.org/ghc/gh
 
 Make sure your system meets all the [prerequisites](https://gitlab.haskell.org/ghc/ghc/-/wikis/building/preparation).
 
+### HLS
+
+There are 3 main ways to compile HLS from source.
+
+1. from hackage (should have up to date version bounds)
+    - `ghcup compile hls --version 1.7.0.0 --ghc 9.2.3`
+2. from git (allows to build latest sources and PRs)
+    - `ghcup compile hls --git-ref master --ghc 9.2.3`
+    - `ghcup compile hls --git-ref a32db0b --ghc 9.2.3`
+    - `ghcup compile hls --git-ref 1.7.0.0 --ghc 9.2.3`
+3. from source distribution that's packaged during release from the corresponding git sources
+    - `ghcup compile hls --source-dist 1.7.0.0 --ghc 9.2.3`
+
+All these use `cabal v2-install` under the hood, so all build components are cached.
+You can pass arbitrary arguments to cabal, e.g. set the index state like so:
+
+```sh
+ghcup compile hls --git-ref master --ghc 9.2.3 -- --index-state=2022-06-12T00:00:00Z --allow-newer
+```
+
+You can pass `--ghc <ver>` multiple times to install for many GHCs at once.
+
+When building from git sources, ghcup will auto-detect the HLS version that the git commit corresponds to
+from the `haskell-language-server.cabal` file. This version might not have been updated since the last release.
+If you want to avoid overwriting the existing installed HLS version, you can instruct ghcup to use `git describe`
+to set the HLS version instead:
+
+```sh
+ghcup compile hls --git-ref master --ghc 9.2.3 --git-describe-version
+```
+
+You can also set the version explicitly:
+
+```sh
+ghcup compile hls --git-ref master --ghc 9.2.3 --overwrite-version 1.7.0.0-p1
+```
+
+As always, check `ghcup compile hls --help`.
+
 ### Cross support
 
 ghcup can compile and install a cross GHC for any target. However, this