tidy-up: git options, ECH, HTTP/3 documentation

- prefer `--branch` over `-b`, where missing.
- add `--depth 1` where missing.
- sync option order between docs and GHA.
- bump quiche and rustls-ffi versions in documentation.
- ECH.md: update for OpenSSL 4.

Closes #21447

diff --git a/.github/workflows/http3-linux.yml b/.github/workflows/http3-linux.yml
index 1b7e1046a323f2dbd6d5ab3911a15d4cd7774537..91699e18b212f0c0aa3749f7da52569842f8d8eb 100644 (file)
--- a/.github/workflows/http3-linux.yml
+++ b/.github/workflows/http3-linux.yml
@@ -225,7 +225,7 @@ jobs:
         if: ${{ steps.cache-openssl-http3-no-deprecated.outputs.cache-hit != 'true' }}
         run: |
           cd ~
-          git clone --quiet --depth 1 -b "openssl-${OPENSSL_VERSION}" https://github.com/openssl/openssl
+          git clone --quiet --depth 1 --branch "openssl-${OPENSSL_VERSION}" https://github.com/openssl/openssl
           cd openssl
           ./config --prefix="$PWD"/build --libdir=lib no-makedepend no-apps no-docs no-tests no-deprecated
           make
@@ -313,7 +313,7 @@ jobs:
         if: ${{ steps.cache-wolfssl.outputs.cache-hit != 'true' }}
         run: |
           cd ~
-          git clone --quiet --depth 1 -b "v${WOLFSSL_VERSION}-stable" https://github.com/wolfSSL/wolfssl
+          git clone --quiet --depth 1 --branch "v${WOLFSSL_VERSION}-stable" https://github.com/wolfSSL/wolfssl
           cd wolfssl
           ./autogen.sh
           ./configure --disable-dependency-tracking --prefix="$PWD"/build --enable-all --enable-quic \
@@ -325,7 +325,7 @@ jobs:
         if: ${{ steps.cache-nghttp3.outputs.cache-hit != 'true' }}
         run: |
           cd ~
-          git clone --quiet --depth 1 -b "v${NGHTTP3_VERSION}" https://github.com/ngtcp2/nghttp3
+          git clone --quiet --depth 1 --branch "v${NGHTTP3_VERSION}" https://github.com/ngtcp2/nghttp3
           cd nghttp3
           git submodule update --init --depth 1
           autoreconf -fi
@@ -338,7 +338,7 @@ jobs:
         # building twice to get crypto libs for ossl, libressl and awslc installed
         run: |
           cd ~
-          git clone --quiet --depth 1 -b "v${NGTCP2_VERSION}" https://github.com/ngtcp2/ngtcp2
+          git clone --quiet --depth 1 --branch "v${NGTCP2_VERSION}" https://github.com/ngtcp2/ngtcp2
           cd ngtcp2
           autoreconf -fi
           ./configure --disable-dependency-tracking --prefix="$PWD"/build --enable-lib-only \
@@ -360,7 +360,7 @@ jobs:
         if: ${{ steps.cache-ngtcp2-openssl-prev.outputs.cache-hit != 'true' }}
         run: |
           cd ~
-          git clone --quiet --depth 1 -b "v${NGTCP2_VERSION}" https://github.com/ngtcp2/ngtcp2 ngtcp2-openssl-prev
+          git clone --quiet --depth 1 --branch "v${NGTCP2_VERSION}" https://github.com/ngtcp2/ngtcp2 ngtcp2-openssl-prev
           cd ngtcp2-openssl-prev
           autoreconf -fi
           ./configure --disable-dependency-tracking --prefix="$PWD"/build --enable-lib-only \
@@ -372,7 +372,7 @@ jobs:
         if: ${{ steps.cache-ngtcp2-boringssl.outputs.cache-hit != 'true' }}
         run: |
           cd ~
-          git clone --quiet --depth 1 -b "v${NGTCP2_VERSION}" https://github.com/ngtcp2/ngtcp2 ngtcp2-boringssl
+          git clone --quiet --depth 1 --branch "v${NGTCP2_VERSION}" https://github.com/ngtcp2/ngtcp2 ngtcp2-boringssl
           cd ngtcp2-boringssl
           autoreconf -fi
           ./configure --disable-dependency-tracking --prefix="$PWD"/build --enable-lib-only \
@@ -385,7 +385,7 @@ jobs:
         if: ${{ steps.cache-nghttp2.outputs.cache-hit != 'true' }}
         run: |
           cd ~
-          git clone --quiet --depth 1 -b "v${NGHTTP2_VERSION}" https://github.com/nghttp2/nghttp2
+          git clone --quiet --depth 1 --branch "v${NGHTTP2_VERSION}" https://github.com/nghttp2/nghttp2
           cd nghttp2
           git submodule update --init --depth 1
           autoreconf -fi
@@ -724,7 +724,7 @@ jobs:
         if: ${{ contains(matrix.build.name, 'quiche') && steps.cache-quiche.outputs.cache-hit != 'true' }}
         run: |
           cd ~
-          git clone --quiet --depth 1 -b "${QUICHE_VERSION}" --recursive https://github.com/cloudflare/quiche
+          git clone --quiet --depth 1 --branch "${QUICHE_VERSION}" --recursive https://github.com/cloudflare/quiche
           cd quiche
           #### Work-around https://github.com/curl/curl/issues/7927 #######
           #### See https://github.com/alexcrichton/cmake-rs/issues/131 ####

diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml
index c7917caf8a3d86b377681829c869f08ea3be480d..d9e09b518782b6cfbae0830c261ff5d070497b38 100644 (file)
--- a/.github/workflows/linux.yml
+++ b/.github/workflows/linux.yml
@@ -749,7 +749,7 @@ jobs:
       - name: 'build openssl (thread sanitizer)'
         if: ${{ contains(matrix.build.install_steps, 'openssl-tsan') && steps.cache-openssl-tsan.outputs.cache-hit != 'true' }}
         run: |
-          git clone --quiet --depth 1 -b "openssl-${OPENSSL_VERSION}" https://github.com/openssl/openssl
+          git clone --quiet --depth 1 --branch "openssl-${OPENSSL_VERSION}" https://github.com/openssl/openssl
           cd openssl
           CC=clang CFLAGS='-fsanitize=thread' LDFLAGS='-fsanitize=thread' ./config --prefix=/home/runner/openssl --libdir=lib no-makedepend no-apps no-docs no-tests
           make

diff --git a/docs/ECH.md b/docs/ECH.md
index 32beba267ee8616b1af2db2eb5d511aa4a0bf842..2a670edd01ca5b1cfa8a2bbe1f1dd645d2947e9a 100644 (file)
--- a/docs/ECH.md
+++ b/docs/ECH.md
@@ -18,11 +18,11 @@ discussion about a good path forward for ECH support in curl.
 
 ## OpenSSL Build
 
-To build the OpenSSL project's ECH feature branch:
+To build OpenSSL 4.0.0+:
 
 ```sh
 cd $HOME/code
-git clone https://github.com/openssl/openssl --branch feature/ech
+git clone --depth 1 --branch openssl-4.0.0 https://github.com/openssl/openssl
 cd openssl
 ./config --libdir=lib --prefix=$HOME/code/openssl-local-inst
 ...stuff...
@@ -36,12 +36,12 @@ To build curl ECH-enabled, making use of the above:
 
 ```sh
 cd $HOME/code
-git clone https://github.com/curl/curl
+git clone --depth 1 https://github.com/curl/curl
 cd curl
 autoreconf -fi
 LDFLAGS="-Wl,-rpath,$HOME/code/openssl-local-inst/lib/" ./configure --with-ssl=$HOME/code/openssl-local-inst --enable-ech
 ...lots of output...
-WARNING: ECH HTTPSRR enabled but marked EXPERIMENTAL...
+WARNING: ECH is enabled but marked EXPERIMENTAL...
 make
 ...lots more output...
 ```
@@ -296,7 +296,7 @@ To build with cmake, assuming our ECH-enabled OpenSSL is as before:
 
 ```sh
 cd $HOME/code
-git clone https://github.com/curl/curl
+git clone --depth 1 https://github.com/curl/curl
 cd curl
 mkdir build
 cd build
@@ -317,7 +317,7 @@ with that, instead of our ECH-enabled OpenSSL:
 
 ```sh
 cd $HOME/code
-git clone https://boringssl.googlesource.com/boringssl
+git clone --depth 1 https://boringssl.googlesource.com/boringssl
 cd boringssl
 cmake -DCMAKE_INSTALL_PREFIX:PATH=$HOME/code/boringssl/inst -DBUILD_SHARED_LIBS=1
 make
@@ -329,7 +329,7 @@ Then:
 
 ```sh
 cd $HOME/code
-git clone https://github.com/curl/curl
+git clone --depth 1 https://github.com/curl/curl
 cd curl
 autoreconf -fi
 LDFLAGS="-Wl,-rpath,$HOME/code/boringssl/inst/lib" ./configure --with-ssl=$HOME/code/boringssl/inst --enable-ech
@@ -351,7 +351,7 @@ wolfSSL also supports ECH and can be used by curl, so here's how:
 
 ```sh
 cd $HOME/code
-git clone https://github.com/wolfSSL/wolfssl
+git clone --depth 1 https://github.com/wolfSSL/wolfssl
 cd wolfssl
 ./autogen.sh
 ./configure --prefix=$HOME/code/wolfssl/inst --enable-ech --enable-debug --enable-opensslextra
@@ -366,7 +366,7 @@ important or else we get build problems with curl below.
 
 ```sh
 cd $HOME/code
-git clone https://github.com/curl/curl
+git clone --depth 1 https://github.com/curl/curl
 cd curl
 autoreconf -fi
 ./configure --with-wolfssl=$HOME/code/wolfssl/inst --enable-ech

diff --git a/docs/HTTP3.md b/docs/HTTP3.md
index 41b1a3fbc13a286ff217d5d5e4c615f5d6c975cf..77fa9664278cbfe019a9ab3917be0714e09ef053 100644 (file)
--- a/docs/HTTP3.md
+++ b/docs/HTTP3.md
@@ -54,7 +54,7 @@ OpenSSL v3.5.0+ requires *ngtcp2* v1.12.0+. Earlier versions do not work.
 Build OpenSSL (v3.5.0+) or fork AWS-LC, BoringSSL, LibreSSL or quictls:
 
      # Instructions for OpenSSL v3.5.0+
-     % git clone --depth 1 -b openssl-$OPENSSL_VERSION https://github.com/openssl/openssl
+     % git clone --depth 1 --branch openssl-$OPENSSL_VERSION https://github.com/openssl/openssl
      % cd openssl
      % ./config --prefix=/path/to/openssl --libdir=lib
      % make
@@ -63,7 +63,7 @@ Build OpenSSL (v3.5.0+) or fork AWS-LC, BoringSSL, LibreSSL or quictls:
 Build nghttp3:
 
      % cd ..
-     % git clone -b $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
+     % git clone --depth 1 --branch $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
      % cd nghttp3
      % git submodule update --init
      % autoreconf -fi
@@ -74,7 +74,7 @@ Build nghttp3:
 Build ngtcp2:
 
      % cd ..
-     % git clone -b $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
+     % git clone --depth 1 --branch $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
      % cd ngtcp2
      % autoreconf -fi
      # Change --with-openssl to --with-boringssl for AWS-LC and BoringSSL
@@ -86,7 +86,7 @@ Build ngtcp2:
 Build curl (with autotools):
 
      % cd ..
-     % git clone https://github.com/curl/curl
+     % git clone --depth 1 https://github.com/curl/curl
      % cd curl
      % autoreconf -fi
      % ./configure PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/openssl/lib" \
@@ -97,7 +97,7 @@ Build curl (with autotools):
 Build curl (with CMake):
 
      % cd ..
-     % git clone https://github.com/curl/curl
+     % git clone --depth 1 https://github.com/curl/curl
      % cd curl
      % PKG_CONFIG_PATH=/path/to/openssl/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld \
        -DOPENSSL_ROOT_DIR=/path/to/openssl -DUSE_NGTCP2=ON
@@ -117,7 +117,7 @@ Build GnuTLS:
 Build nghttp3:
 
      % cd ..
-     % git clone -b $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
+     % git clone --depth 1 --branch $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
      % cd nghttp3
      % git submodule update --init
      % autoreconf -fi
@@ -128,7 +128,7 @@ Build nghttp3:
 Build ngtcp2:
 
      % cd ..
-     % git clone -b $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
+     % git clone --depth 1 --branch $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
      % cd ngtcp2
      % autoreconf -fi
      % ./configure PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/gnutls/lib" \
@@ -139,7 +139,7 @@ Build ngtcp2:
 Build curl (with autotools):
 
      % cd ..
-     % git clone https://github.com/curl/curl
+     % git clone --depth 1 https://github.com/curl/curl
      % cd curl
      % autoreconf -fi
      % ./configure PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig --with-gnutls=/path/to/gnutls --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3
@@ -149,7 +149,7 @@ Build curl (with autotools):
 Build curl (with CMake):
 
      % cd ..
-     % git clone https://github.com/curl/curl
+     % git clone --depth 1 https://github.com/curl/curl
      % cd curl
      % PKG_CONFIG_PATH=/path/to/gnutls/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld -DCURL_USE_GNUTLS=ON -DUSE_NGTCP2=ON
      % cmake --build bld
@@ -158,7 +158,7 @@ Build curl (with CMake):
 
 Build wolfSSL:
 
-     % git clone https://github.com/wolfSSL/wolfssl
+     % git clone --depth 1 https://github.com/wolfSSL/wolfssl
      % cd wolfssl
      % autoreconf -fi
      % ./configure --prefix=/path/to/wolfssl --enable-quic --enable-session-ticket --enable-earlydata --enable-psk --enable-harden --enable-altcertchains
@@ -168,7 +168,7 @@ Build wolfSSL:
 Build nghttp3:
 
      % cd ..
-     % git clone -b $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
+     % git clone --depth 1 --branch $NGHTTP3_VERSION https://github.com/ngtcp2/nghttp3
      % cd nghttp3
      % git submodule update --init
      % autoreconf -fi
@@ -179,7 +179,7 @@ Build nghttp3:
 Build ngtcp2:
 
      % cd ..
-     % git clone -b $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
+     % git clone --depth 1 --branch $NGTCP2_VERSION https://github.com/ngtcp2/ngtcp2
      % cd ngtcp2
      % autoreconf -fi
      % ./configure PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig LDFLAGS="-Wl,-rpath,/path/to/wolfssl/lib" \
@@ -190,7 +190,7 @@ Build ngtcp2:
 Build curl (with autotools):
 
      % cd ..
-     % git clone https://github.com/curl/curl
+     % git clone --depth 1 https://github.com/curl/curl
      % cd curl
      % autoreconf -fi
      % ./configure PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig --with-wolfssl=/path/to/wolfssl --with-ngtcp2=/path/to/ngtcp2 --with-nghttp3=/path/to/nghttp3
@@ -200,7 +200,7 @@ Build curl (with autotools):
 Build curl (with CMake):
 
      % cd ..
-     % git clone https://github.com/curl/curl
+     % git clone --depth 1 https://github.com/curl/curl
      % cd curl
      % PKG_CONFIG_PATH=/path/to/wolfssl/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig cmake -B bld -DCURL_USE_WOLFSSL=ON -DUSE_NGTCP2=ON
      % cmake --build bld
@@ -217,7 +217,7 @@ but in case of problems, we recommend their latest release tag.
 
 Build quiche and BoringSSL:
 
-     % git clone --recursive -b 0.22.0 https://github.com/cloudflare/quiche
+     % git clone --depth 1 --branch 0.24.7 --recursive https://github.com/cloudflare/quiche
      % cd quiche
      % cargo build --package quiche --release --features ffi,pkg-config-meta,qlog
      % ln -s libquiche.so target/release/libquiche.so.0
@@ -227,7 +227,7 @@ Build quiche and BoringSSL:
 Build curl:
 
      % cd ..
-     % git clone https://github.com/curl/curl
+     % git clone --depth 1 https://github.com/curl/curl
      % cd curl
      % autoreconf -fi
      % ./configure LDFLAGS="-Wl,-rpath,$PWD/../quiche/target/release" \
@@ -326,7 +326,7 @@ above.
 
 Get, build and install nghttp2:
 
-     % git clone https://github.com/nghttp2/nghttp2
+     % git clone --depth 1 https://github.com/nghttp2/nghttp2
      % cd nghttp2
      % autoreconf -fi
      % PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/path/to/quictls/lib/pkgconfig:/path/to/nghttp3/lib/pkgconfig:/path/to/ngtcp2/lib/pkgconfig \

diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 619df5cc89e526e7f01fd2561aba9301fca9dc27..db743e0554e86fbd01f7f90d9b70e53f659b18a3 100644 (file)
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -18,7 +18,7 @@ libcurl from [source code](https://curl.se/download.html).
 You can download and install curl and libcurl using
 the [vcpkg](https://github.com/Microsoft/vcpkg) dependency manager:
 
-    git clone https://github.com/Microsoft/vcpkg
+    git clone --depth 1 https://github.com/Microsoft/vcpkg
     cd vcpkg
     ./bootstrap-vcpkg.sh
     ./vcpkg integrate install

diff --git a/docs/RUSTLS.md b/docs/RUSTLS.md
index 4f904a97e082960f92b0d556c5c6db3e52a2f7f4..b1c8044e8e3eaafec79d742f93dffaa03d5ede66 100644 (file)
--- a/docs/RUSTLS.md
+++ b/docs/RUSTLS.md
@@ -27,7 +27,7 @@ differ between distributions.
 
 Once installed, build `curl` using `--with-rustls`.
 
-    % git clone https://github.com/curl/curl
+    % git clone --depth 1 https://github.com/curl/curl
     % cd curl
     % autoreconf -fi
     % ./configure --with-rustls
@@ -43,7 +43,7 @@ Download the appropriate archive for your platform and extract it to a directory
 
 Once downloaded, build `curl` using `--with-rustls` and the path to the extracted binaries.
 
-    % git clone https://github.com/curl/curl
+    % git clone --depth 1 https://github.com/curl/curl
     % cd curl
     % autoreconf -fi
     % ./configure --with-rustls=${HOME}/rustls-ffi-built
@@ -63,13 +63,13 @@ To install `cargo-c`, use your [package manager][cargo-c pkg], download
 
 Next, check out, build, and install the appropriate version of `rustls-ffi` using `cargo`:
 
-    % git clone https://github.com/rustls/rustls-ffi -b v0.15.0
+    % git clone --depth 1 --branch v0.15.3 https://github.com/rustls/rustls-ffi
     % cd rustls-ffi
     % cargo capi install --release --prefix=${HOME}/rustls-ffi-built
 
 Now configure and build `curl` using `--with-rustls`:
 
-    % git clone https://github.com/curl/curl
+    % git clone --depth 1 https://github.com/curl/curl
     % cd curl
     % autoreconf -fi
     % ./configure --with-rustls=${HOME}/rustls-ffi-built