{"thread":{"id":"51146","subject":"Slightly confusing documentation for \"git clone --recursive\"","startedAt":"2019-05-21T21:26:13Z","lastAt":"2019-05-21T21:26:13Z","messageCount":1,"participants":["Keith Thompson"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"376017","messageId":"CAAHpriPYxFv=vET92DonRb=kV_NWEDFe0nRnNH2wxcwP78BDdA@mail.gmail.com","threadId":"51146","inReplyTo":null,"subject":"Slightly confusing documentation for \"git clone --recursive\"","fromName":"Keith Thompson","fromEmail":"keith.s.thompson@gmail.com","sentAt":"2019-05-21T21:25:57Z","receivedAt":"2019-05-21T21:26:13Z","isPatch":false,"sender":{"key":"keith.s.thompson@gmail.com","avatar":"https://gravatar.com/avatar/2cd597778c4fcea958f6ff673882f768bd9506a95bc509925cb7eff718601cd5?d=mp&s=160"},"body":"In builtin/clone.c, the handling of \"--recursive\" as an alias for\n\"--recurse-submodules\" changed between\nv2.22.0-rc0 and v2.22.0-rc1. This report refers to the way it's\ndocumented in the newest version\nand suggests some improvements.\n\nThe short help (git clone -h) says:\n\n    --recursive[=<pathspec>]\n                          initialize submodules in the clone\n    --recurse-submodules[=<pathspec>]\n                          initialize submodules in the clone\n\nIt repeats the same description, but doesn't explicitly say that\nthey're equivalent. I can imagine\nthis causing some confusion. I might have wondered if there's some\nsubtle difference between them.\nSuggested change:\n\n    --recursive[=<pathspec>]\n    --recurse-submodules[=<pathspec>]\n                          initialize submodules in the clone\n\nThe long help (\"git clone --help\") says:\n\n       --recurse-submodules[=<pathspec]\n           After the clone is created, initialize and clone submodules within\n           based on the provided pathspec. If no pathspec is provided, all\n           submodules are initialized and cloned. This option can be given\n           multiple times for pathspecs consisting of multiple entries. The\n           resulting clone has submodule.active set to the provided pathspec,\n           or \".\" (meaning all submodules) if no pathspec is provided.\n\n           Submodules are initialized and cloned using their default settings.\n           This is equivalent to running git submodule update --init\n           --recursive <pathspec> immediately after the clone is finished.\n           This option is ignored if the cloned repository does not have a\n           worktree/checkout (i.e. if any of --no-checkout/-n, --bare, or\n           --mirror is given)\n\nThe \"--recursive\" spelling is not documented, but is used in an example in\nthe documentation for \"--recursive-submodules\". Suggested change:\n\n       --recursive=<pathspec]\n       --recurse-submodules[=<pathspec]\n           After the clone is created, initialize and clone submodules within\n           [... rest of description as before]\n"}]}