Questions on passing --depth to git-clone vs. git-fetch

It is not wrong to talk about "revisions" here, but in this context revisions are always commits, and that is how we already name it in the git-fetch docs. So align the docs by always referring to "commits".

The original wording sounded as if --depth could only be used to deepen or shorten the history of existing repos. However, that is not the case. In a workflow like

     $ git init
     $ git remote add origin https://github.com/git/git.git
     $ git fetch --depth=1

The newly initialized repo is properly created as a shallow repo.

Hi,

I recently compared the results of doing

    $ git clone --depth=1 https://github.com/git/git.git git-clone-depth-1

versus

    $ mkdir git-fetch-depth-1
    $ cd git-fetch-depth-1
    $ git init
    $ git remote add origin https://github.com/git/git.git
    $ git fetch --depth=1

and noticed a few things:

1. The docs of clone [1] say about --depth "Create a shallow clone with a history truncated to the specified number of revisions" while for fetch the docs [2] say "[...] to the specified number of commits [...]". As in this particular case revision are always commits, I think the clone docs should also say "commits".

2. In the fetch docs --depth is described to "Deepen or shorten the history of a shallow repository created by git clone". That sounds as if my example from above where I initialze a repo manually would not allow fetch to be called with --depth as I did not clone before. But in fact my example works fine. I guess we need some clarfication in the wording here.

3. When running "git log --all -oneline" in the two working trees I get different results, which is not what I'd expect:

    $ cd git-clone-depth-1
    $ git log --all --oneline
      7548842 Git 2.7

versus

    $ cd git-fetch-depth-1
    $ git log --all --oneline
      b819526 Merge branch 'jk/notes-merge-from-anywhere' into pu
      e2281f4 What's cooking (2016/01 #01)
      ef7b32d Sync with 2.7
      7548842 Git 2.7
      833e482 Git 2.6.5

So in the clone case only the specified number of commits from the tip of the default branch (master in this case) is fetched, not of each remote branch history. fetch in the other hand really gets the specified number of commits from the tip of each remote branch history. I don't know whether this behavior is inded or not as I cannot find any docs on it either way. But it seems inconsistent to me that clone with --depth only gets the history for the default branch, as clone without --depth would give me the history of all branches.

For completeness, I'm using Git for Windows 2.7.

Any comments?

[1] https://git-scm.com/docs/git-clone
[1] https://git-scm.com/docs/git-fetch

--
Sebastian Schuberth

--
To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html

I think the culprit is the "git remote add" line. "git clone --depth" by default will fetch only one branch (aka --single-branch option in git-clone). But I suspect when you add a new remote, the default

It is confusing to document how --depth behaves as part of the --single-branch docs. Better move that part to the --depth docs, saying that it implies --single-branch by default.

Signed-off-by Sebastian Schuberth <[email protected]>

---

 Documentation/git-clone.txt | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

Documentation/git-clone.txt +4 -5

index 6bf000d..943de8b 100644
@@ -190,15 +190,14 @@ objects from the source repository into a pack in the cloned repository.
 
 --depth <depth>::
 	Create a 'shallow' clone with a history truncated to the
-	specified number of revisions.
+	specified number of revisions. Implies `--single-branch` unless
+	`--no-single-branch` is given to fetch the histories near the
+	tips of all branches.
 
 --[no-]single-branch::
 	Clone only the history leading to the tip of a single branch,
 	either specified by the `--branch` option or the primary
-	branch remote's `HEAD` points at. When creating a shallow
-	clone with the `--depth` option, this is the default, unless
-	`--no-single-branch` is given to fetch the histories near the
-	tips of all branches.
+	branch remote's `HEAD` points at.
 	Further fetches into the resulting repository will only update the
 	remote-tracking branch for the branch this option was used for the
 	initial cloning.  If the HEAD at the remote did not point at any