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

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

[Sebastian Schuberth]

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

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

[Duy Nguyen]

On Wed, Jan 6, 2016 at 7:30 PM, Sebastian Schuberth
<sschuberth@gmail.com> wrote:
> 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:

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
refspec is to get all refs. So "git fetch --depth=1" means fetch _all_
refs, each one has maximum one commit. "git log --graph --decorate"
should show this clearer.

> 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 majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html



-- 
Duy

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

[Sebastian Schuberth]

On 1/6/2016 13:41, Duy Nguyen wrote:

> 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

Now that you mention it I see this being documented as part of 
--single-branch instead of --depth, which I think is confusing. I'll 
send a patch.

-- 
Sebastian Schuberth

[PATCH] docs: clarify that passing --depth to git-clone implies --single-branch

[Sebastian Schuberth]

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 <sschuberth@gmail.com>
---
 Documentation/git-clone.txt | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 6bf000d..943de8b 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -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
-- 
2.7.0.windows.1

Re: [PATCH] docs: clarify that passing --depth to git-clone implies --single-branch

[Junio C Hamano]

Sebastian Schuberth <sschuberth@gmail.com> writes:

> 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 <sschuberth@gmail.com>
> ---

Yeah, the new organization is much easier and intuitive to follow.

Thanks.


>  Documentation/git-clone.txt | 9 ++++-----
>  1 file changed, 4 insertions(+), 5 deletions(-)
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index 6bf000d..943de8b 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -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

[PATCH] docs: say "commits" in the --depth option wording for git-clone

[Sebastian Schuberth]

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".
---
 Documentation/git-clone.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 943de8b..789b668 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -190,7 +190,7 @@ 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. Implies `--single-branch` unless
+	specified number of commits. Implies `--single-branch` unless
 	`--no-single-branch` is given to fetch the histories near the
 	tips of all branches.
 
-- 
2.7.0.windows.1

[PATCH] docs: clarify that --depth for git-fetch works with newly initialized repos

[Sebastian Schuberth]

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.
---
 Documentation/fetch-options.txt | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/Documentation/fetch-options.txt b/Documentation/fetch-options.txt
index 45583d8..78cd265 100644
--- a/Documentation/fetch-options.txt
+++ b/Documentation/fetch-options.txt
@@ -8,10 +8,11 @@
 	option old data in `.git/FETCH_HEAD` will be overwritten.
 
 --depth=<depth>::
-	Deepen or shorten the history of a 'shallow' repository created by
-	`git clone` with `--depth=<depth>` option (see linkgit:git-clone[1])
-	to the specified number of commits from the tip of each remote
-	branch history. Tags for the deepened commits are not fetched.
+	Limit fetching to the specified number of commits from the tip of
+	each remote branch history. If fetching to a 'shallow' repository
+	created by `git clone` with `--depth=<depth>` option (see
+	linkgit:git-clone[1]), deepen or shorten the history to the specified
+	number of commits. Tags for the deepened commits are not fetched.
 
 --unshallow::
 	If the source repository is complete, convert a shallow
-- 
2.7.0.windows.1

Re: [PATCH] docs: say "commits" in the --depth option wording for git-clone

[Sebastian Schuberth]

On 08.01.2016 10:18, Sebastian Schuberth wrote:

> 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".

Sorry for the missing sign-off, feel free to amend that in pu:

Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com>

-- 
Sebastian Schuberth

Re: [PATCH] docs: clarify that --depth for git-fetch works with newly initialized repos

[Sebastian Schuberth]

On 08.01.2016 10:32, Sebastian Schuberth wrote:

> 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.

Sorry for the missing sign-off, feel free to amend that in pu:

Signed-off-by: Sebastian Schuberth <sschuberth@gmail.com>

-- 
Sebastian Schuberth