Re: [PATCH] submodule documentation: Reorder introductory paragraphs
On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano gits...@pobox.com wrote: Stefan Beller sbel...@google.com writes: DESCRIPTION --- +This command will inspect, update and manage submodules. +Submodules allow you to keep another Git repository in a subdirectory +of your repository. The other repository has its own history,... The first line somehow bothered me, so I took a random sample of commands I often use: git log Shows the commit logs. git show Shows one or more objects (blobs, trees, tags and commits). git commit Stores the current contents of the index in a new commit along with a log message from the user describing the changes. git diff Show changes between the working tree and the index or a tree, changes between the index and a tree, changes between two trees, changes between two blob objects, or changes between two files on disk. git push Updates remote refs using local refs, while sending objects necessary to complete the given refs. I _think_ what bothered me was This command (drawing the reaction eh, what other command are you going to talk about in the help page for this command?). Perhaps Inspects, updates and manages submodules. may match the style of other help pages better. Sounds much better than my patch. On the other hand, I probably would not have felt such a strong strangeness if it were described like this: This command can help you inspect, update, and manage submodules. I haven't analized it enough to say why it is, but I suspect it has something to do with (my own) perception that git submodule is not very essential to do any of these things (i.e. .gitmodules is a very simple text file), but is primarily a helpful wrapper. My perception is that the submodule man page similar to the subtree man page tries to explain an underlying concept as well. The other man pages you quoted don't do that as the concepts are explained elsewhere(?) As a side note: In the Gerrit test suite I use the JGit implementation of the config command to write out .gitmodules files. So maybe `git submodule` can be understood as a specialized form of `git config`. The description of git config, on which I have a similar perception, seem to match ;-) git config You can query/set/replace/unset options with this command. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
On Tue, May 26, 2015 at 10:53:15AM -0700, Stefan Beller wrote: On Mon, May 25, 2015 at 3:00 PM, Junio C Hamano gits...@pobox.com wrote: Stefan Beller sbel...@google.com writes: On the other hand, I probably would not have felt such a strong strangeness if it were described like this: This command can help you inspect, update, and manage submodules. I haven't analized it enough to say why it is, but I suspect it has something to do with (my own) perception that git submodule is not very essential to do any of these things (i.e. .gitmodules is a very simple text file), but is primarily a helpful wrapper. My perception is that the submodule man page similar to the subtree man page tries to explain an underlying concept as well. The other man pages you quoted don't do that as the concepts are explained elsewhere(?) As a side note: In the Gerrit test suite I use the JGit implementation of the config command to write out .gitmodules files. So maybe `git submodule` can be understood as a specialized form of `git config`. I do not agree here. That view is too limited. Since in the case of e.g. 'git submodule add‘ it does not only change the .gitmodules file but adds a gitlink entry to the index, moves the database into .git/modules, ... . And even though it is currently not doing much more it might in the future. E.g. it might make sense to add a 'git submodule gc' command which allows the user to purge unused submodule databases from the .git/modules directory. So I would say it is: a helper or a tool for submodules. Nothing less nothing more. But on the other hand the same is true for other porcelain commands like e.g. 'git commit'. If you take a look at gitcore-tutorial you could also describe it as a wrapper for write-tree, commit-tree and update-ref to create a commit. Yet the man page says: Record changes to the repository. So I am not sure where to draw the line between wrapper and essential command. As a user I would see it as quite essential since for adding a submodule I would need to remember a couple of things: * clone the database into .git/modules * create the gitlink file * checkout the files to the desired directory * add the url to the .gitmodules file So why not go with Junios first suggestion and lets drop the This command can help you... and say: Inspect, update and manage submodules. Cheers Heiko -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
Stefan Beller sbel...@google.com writes: DESCRIPTION --- +This command will inspect, update and manage submodules. +Submodules allow you to keep another Git repository in a subdirectory +of your repository. The other repository has its own history,... The first line somehow bothered me, so I took a random sample of commands I often use: git log Shows the commit logs. git show Shows one or more objects (blobs, trees, tags and commits). git commit Stores the current contents of the index in a new commit along with a log message from the user describing the changes. git diff Show changes between the working tree and the index or a tree, changes between the index and a tree, changes between two trees, changes between two blob objects, or changes between two files on disk. git push Updates remote refs using local refs, while sending objects necessary to complete the given refs. I _think_ what bothered me was This command (drawing the reaction eh, what other command are you going to talk about in the help page for this command?). Perhaps Inspects, updates and manages submodules. may match the style of other help pages better. On the other hand, I probably would not have felt such a strong strangeness if it were described like this: This command can help you inspect, update, and manage submodules. I haven't analized it enough to say why it is, but I suspect it has something to do with (my own) perception that git submodule is not very essential to do any of these things (i.e. .gitmodules is a very simple text file), but is primarily a helpful wrapper. The description of git config, on which I have a similar perception, seem to match ;-) git config You can query/set/replace/unset options with this command. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
From: Stefan Beller sbel...@google.com On Thu, May 21, 2015 at 1:03 PM, Philip Oakley philipoak...@iee.org wrote: +Submodules are not to be confused with remotes, which are meant +mainly for branches of the same project; This use of 'branches' didn't work for me. remotes are meant mainly for branches of the same project ? Maybe Submodules should not be confused with remote repositories, which are meant to track the same repository, just at another location; ... ? Though I'm not yet completely happy with that either. I like that better. I was going to check what the git glossary said a remote was, but the commute to work beckons... Philip -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
From: Stefan Beller sbel...@google.com It's better to start the man page with a description of what submodules actually are instead of saying what they are not. Reorder the paragraphs such that the first short paragraph introduces the submodule concept, the second paragraph highlights the usage of the submodule command, the third paragraph giving background information, and finally the fourth paragraph discusing alternatives such as subtrees and remotes, which we don't want to be confused with. This ordering deepens the knowledge on submodules with each paragraph. First the basic questions like How/what will be answered, while the underlying concepts will be taught at a later time. Making sure it is not confused with subtrees and remotes is not really enhancing knowledge of submodules itself, but rather painting the big picture of git concepts, so you could also argue to have it as the second paragraph. Personally I think this may confuse readers, specially newcomers though. Additionally to reordering the paragraphs, they have been slightly reworded. Signed-off-by: Stefan Beller sbel...@google.com --- For now I used a part of Junios suggestion Submodules are not to be confused with remotes, which are other repositories of the same project; I like the are not to be confused part, as they warn the reader that there will be a paragraph not as concise but touching other commands and topics. Documentation/git-submodule.txt | 50 ++--- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c25916..d126c86 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -25,22 +25,17 @@ SYNOPSIS DESCRIPTION --- -Submodules allow foreign repositories to be embedded within -a dedicated subdirectory of the source tree, always pointed -at a particular commit. +This command will inspect, update and manage submodules. -They are not to be confused with remotes, which are meant mainly -for branches of the same project; submodules are meant for -different projects you would like to make part of your source tree, -while the history of the two projects still stays completely -independent and you cannot modify the contents of the submodule -from within the main project. -If you want to merge the project histories and want to treat the -aggregated whole as a single project from then on, you may want to -add a remote for the other project and use the 'subtree' merge strategy, -instead of treating the other project as a submodule. Directories -that come from both projects can be cloned and checked out as a whole -if you choose to go that route. +Submodules allow you to keep another Git repository in a subdirectory +of your repository. The other repository has its own history, which does not +interfere with the history of the current repository. This can be used to +have external dependencies such as libraries for example. + +When cloning or pulling a repository containing submodules however, +these will not be checked out by default; the 'init' and 'update' +subcommands will maintain submodules checked out and at +appropriate revision in your working tree. Submodules are composed from a so-called `gitlink` tree entry in the main repository that refers to a particular commit object @@ -51,19 +46,18 @@ describes the default URL the submodule shall be cloned from. The logical name can be used for overriding this URL within your local repository configuration (see 'submodule init'). -This command will manage the tree entries and contents of the -gitmodules file for you, as well as inspect the status of your -submodules and update them. -When adding a new submodule to the tree, the 'add' subcommand -is to be used. However, when pulling a tree containing submodules, -these will not be checked out by default; -the 'init' and 'update' subcommands will maintain submodules -checked out and at appropriate revision in your working tree. -You can briefly inspect the up-to-date status of your submodules -using the 'status' subcommand and get a detailed overview of the -difference between the index and checkouts using the 'summary' -subcommand. - +Submodules are not to be confused with remotes, which are other +repositories of the same project; I said (22 May 2015 20:47): if a nice well understood explanatory phrase can be found - I'm happy with yours. Many thanks submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy,
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
From: Stefan Beller sbel...@google.com
On Fri, May 22, 2015 at 10:35 AM, Philip Oakley philipoak...@iee.org
wrote:
From: Stefan Beller sbel...@google.com
On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano gits...@pobox.com
wrote:
Stefan Beller sbel...@google.com writes:
On Thu, May 21, 2015 at 1:03 PM, Philip Oakley
philipoak...@iee.org
wrote:
+Submodules are not to be confused with remotes, which are meant
+mainly for branches of the same project;
This use of 'branches' didn't work for me. remotes are meant
mainly
for
branches of the same project ?
The branch in the original is used in a much wider sense than
usual branch (i.e. ref/heads/ thing you have locally); it refers to
forks of the same project but with a bit of twist. When you say
repository A is a fork of the same project as my local repository,
you would give an impression that A is not the authoritative copy
of
the project. But you can say my repository and that repository A
are branches of the same project, you give zero information as to
A's authoritativeness.
While this is correct, I think it is also confusing, because
'branch'
is a command which deals with local branches only in my perception
To deal with remote branches you need to use the commands
{remote, fetch, pull}.
So when someone mentions branch I need to think of local
operations
in one repository and not on different distributed histories.
If we are having difficulties defining a remote here (its not
defined in
gitglossary.txt anyway),
Now that we have a discussion on what remotes are, I'll send a patch
for that
as well.
why not simply put a full stop (period) after the
Submodules are not to be confused with remotes., and bypass the
problem,
avoiding digging the hole deeper.
I think we should dig deeper and point out the differences as it may
not be clear what
the differences are for new comers. Not digging deeper sounds to me
like saying
'git frotz' is not to be confused with 'git bar' FULL STOP AND I
WONT TELL YOU WHY!
Hi Stefan,
This was more of a case of simply a full stop, 'cos I can't easily tell
you why ;-). I've seen too many work situations (*) where colleagues
just dig deeper when they should stop digging, hence the note. It may be
that the style of reason could be changed. This is the final
introductory paragraph and was being pushed down partly because of this
problem (explaining things by saying what its not).
(*) The usual phrase in a report would be A moments thought will show
that ... for those concepts that would take two pages to explain and
would still be misunderstood by the unthinking folks.
That all said, if a nice well understood explanatory phrase can be found
then I'm all for it.
which is not helpful. (Why is the documentation pointing out there is
a difference to
that other command/concept, but not saying what is different?)
Submodules should not be confused with remote repositories,
which
are
meant to track the same repository, just at another location;
...
I do not think this is a great improvement. You now conflated
repository to mean project in the latter half of the sentence,
while you are trying to explain what a remote repository is.
That's true.
Your copy of git.git is not the same repository as mine; they have
different histories. Both repositories are used to work on the
same
project. submoules are not remotes, which are other repositories
of the same project, perhaps?
That makes sense.
If maybe that the feature we should pick on is the common root of the
development between the local and remote repository, and quite
distinct for
the submodule. This allows remotes to be on the same machine, as well
as
distant machines and server.
I don't think this is actually true for all remotes. Think of shallow
clones
(they have no root or a different root) or even subtrees which are
pulled
in via a remotes?
I'd avoided mentioning that potential explanation mud-hole on the same
basis that it would be hard.
The main thing about remotes is not being here (as in part of this
repository. As you point out it can be nearby in the local fs or even
on
another machine, or in the cloud)
It is I believe technically possible to have a submodule which is its
own
super project, with and without recursion, but would be very
atypical, and
would belong in the 'don't do that' category
regards
Philip
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
Stefan Beller sbel...@google.com writes: On Thu, May 21, 2015 at 1:03 PM, Philip Oakley philipoak...@iee.org wrote: +Submodules are not to be confused with remotes, which are meant +mainly for branches of the same project; This use of 'branches' didn't work for me. remotes are meant mainly for branches of the same project ? The branch in the original is used in a much wider sense than usual branch (i.e. ref/heads/ thing you have locally); it refers to forks of the same project but with a bit of twist. When you say repository A is a fork of the same project as my local repository, you would give an impression that A is not the authoritative copy of the project. But you can say my repository and that repository A are branches of the same project, you give zero information as to A's authoritativeness. Submodules should not be confused with remote repositories, which are meant to track the same repository, just at another location; ... I do not think this is a great improvement. You now conflated repository to mean project in the latter half of the sentence, while you are trying to explain what a remote repository is. Your copy of git.git is not the same repository as mine; they have different histories. Both repositories are used to work on the same project. submoules are not remotes, which are other repositories of the same project, perhaps? -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
Stefan Beller sbel...@google.com writes: On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano gits...@pobox.com wrote: Stefan Beller sbel...@google.com writes: On Thu, May 21, 2015 at 1:03 PM, Philip Oakley philipoak...@iee.org wrote: +Submodules are not to be confused with remotes, which are meant +mainly for branches of the same project; This use of 'branches' didn't work for me. remotes are meant mainly for branches of the same project ? The branch in the original is used in a much wider sense than usual branch (i.e. ref/heads/ thing you have locally); it refers to forks of the same project but with a bit of twist. When you say repository A is a fork of the same project as my local repository, you would give an impression that A is not the authoritative copy of the project. But you can say my repository and that repository A are branches of the same project, you give zero information as to A's authoritativeness. While this is correct, I think it is also confusing, because... Oh, no question about it. In modern Git parlance, it confuses by conflating 'branch' (which is local ref/heads/ thing) with something entirely different. I wasn't saying 'branch' is correct and we should keep the description that way. If you dig ancient list archives, you see Linus and I using 'branch' to mean your copy of the project quite often, and that is likely where the above phrase originated. It was one of those explaining historical background, nothing more. I probably should start prefixing all my explaining historical background sentences as such. I do not think this is a great improvement. You now conflated repository to mean project in the latter half of the sentence, while you are trying to explain what a remote repository is. That's true. Your copy of git.git is not the same repository as mine; they have different histories. Both repositories are used to work on the same project. submoules are not remotes, which are other repositories of the same project, perhaps? That makes sense. Thanks. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] submodule documentation: Reorder introductory paragraphs
It's better to start the man page with a description of what submodules actually are instead of saying what they are not. Reorder the paragraphs such that the first short paragraph introduces the submodule concept, the second paragraph highlights the usage of the submodule command, the third paragraph giving background information, and finally the fourth paragraph discusing alternatives such as subtrees and remotes, which we don't want to be confused with. This ordering deepens the knowledge on submodules with each paragraph. First the basic questions like How/what will be answered, while the underlying concepts will be taught at a later time. Making sure it is not confused with subtrees and remotes is not really enhancing knowledge of submodules itself, but rather painting the big picture of git concepts, so you could also argue to have it as the second paragraph. Personally I think this may confuse readers, specially newcomers though. Additionally to reordering the paragraphs, they have been slightly reworded. Signed-off-by: Stefan Beller sbel...@google.com --- For now I used a part of Junios suggestion Submodules are not to be confused with remotes, which are other repositories of the same project; I like the are not to be confused part, as they warn the reader that there will be a paragraph not as concise but touching other commands and topics. Documentation/git-submodule.txt | 50 ++--- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c25916..d126c86 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -25,22 +25,17 @@ SYNOPSIS DESCRIPTION --- -Submodules allow foreign repositories to be embedded within -a dedicated subdirectory of the source tree, always pointed -at a particular commit. +This command will inspect, update and manage submodules. -They are not to be confused with remotes, which are meant mainly -for branches of the same project; submodules are meant for -different projects you would like to make part of your source tree, -while the history of the two projects still stays completely -independent and you cannot modify the contents of the submodule -from within the main project. -If you want to merge the project histories and want to treat the -aggregated whole as a single project from then on, you may want to -add a remote for the other project and use the 'subtree' merge strategy, -instead of treating the other project as a submodule. Directories -that come from both projects can be cloned and checked out as a whole -if you choose to go that route. +Submodules allow you to keep another Git repository in a subdirectory +of your repository. The other repository has its own history, which does not +interfere with the history of the current repository. This can be used to +have external dependencies such as libraries for example. + +When cloning or pulling a repository containing submodules however, +these will not be checked out by default; the 'init' and 'update' +subcommands will maintain submodules checked out and at +appropriate revision in your working tree. Submodules are composed from a so-called `gitlink` tree entry in the main repository that refers to a particular commit object @@ -51,19 +46,18 @@ describes the default URL the submodule shall be cloned from. The logical name can be used for overriding this URL within your local repository configuration (see 'submodule init'). -This command will manage the tree entries and contents of the -gitmodules file for you, as well as inspect the status of your -submodules and update them. -When adding a new submodule to the tree, the 'add' subcommand -is to be used. However, when pulling a tree containing submodules, -these will not be checked out by default; -the 'init' and 'update' subcommands will maintain submodules -checked out and at appropriate revision in your working tree. -You can briefly inspect the up-to-date status of your submodules -using the 'status' subcommand and get a detailed overview of the -difference between the index and checkouts using the 'summary' -subcommand. - +Submodules are not to be confused with remotes, which are other +repositories of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. COMMANDS --
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano gits...@pobox.com wrote:
Stefan Beller sbel...@google.com writes:
On Thu, May 21, 2015 at 1:03 PM, Philip Oakley philipoak...@iee.org wrote:
+Submodules are not to be confused with remotes, which are meant
+mainly for branches of the same project;
This use of 'branches' didn't work for me. remotes are meant mainly for
branches of the same project ?
The branch in the original is used in a much wider sense than
usual branch (i.e. ref/heads/ thing you have locally); it refers to
forks of the same project but with a bit of twist. When you say
repository A is a fork of the same project as my local repository,
you would give an impression that A is not the authoritative copy of
the project. But you can say my repository and that repository A
are branches of the same project, you give zero information as to
A's authoritativeness.
While this is correct, I think it is also confusing, because 'branch'
is a command which deals with local branches only in my perception
To deal with remote branches you need to use the commands
{remote, fetch, pull}.
So when someone mentions branch I need to think of local operations
in one repository and not on different distributed histories.
Submodules should not be confused with remote repositories, which are
meant to track the same repository, just at another location; ...
I do not think this is a great improvement. You now conflated
repository to mean project in the latter half of the sentence,
while you are trying to explain what a remote repository is.
That's true.
Your copy of git.git is not the same repository as mine; they have
different histories. Both repositories are used to work on the same
project. submoules are not remotes, which are other repositories
of the same project, perhaps?
That makes sense.
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
From: Stefan Beller sbel...@google.com
On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano gits...@pobox.com
wrote:
Stefan Beller sbel...@google.com writes:
On Thu, May 21, 2015 at 1:03 PM, Philip Oakley
philipoak...@iee.org wrote:
+Submodules are not to be confused with remotes, which are meant
+mainly for branches of the same project;
This use of 'branches' didn't work for me. remotes are meant
mainly for
branches of the same project ?
The branch in the original is used in a much wider sense than
usual branch (i.e. ref/heads/ thing you have locally); it refers to
forks of the same project but with a bit of twist. When you say
repository A is a fork of the same project as my local repository,
you would give an impression that A is not the authoritative copy of
the project. But you can say my repository and that repository A
are branches of the same project, you give zero information as to
A's authoritativeness.
While this is correct, I think it is also confusing, because 'branch'
is a command which deals with local branches only in my perception
To deal with remote branches you need to use the commands
{remote, fetch, pull}.
So when someone mentions branch I need to think of local operations
in one repository and not on different distributed histories.
If we are having difficulties defining a remote here (its not defined
in gitglossary.txt anyway), why not simply put a full stop (period)
after the Submodules are not to be confused with remotes., and bypass
the problem, avoiding digging the hole deeper.
Submodules should not be confused with remote repositories,
which are
meant to track the same repository, just at another location;
...
I do not think this is a great improvement. You now conflated
repository to mean project in the latter half of the sentence,
while you are trying to explain what a remote repository is.
That's true.
Your copy of git.git is not the same repository as mine; they have
different histories. Both repositories are used to work on the same
project. submoules are not remotes, which are other repositories
of the same project, perhaps?
That makes sense.
If maybe that the feature we should pick on is the common root of the
development between the local and remote repository, and quite distinct
for the submodule. This allows remotes to be on the same machine, as
well as distant machines and server.
It is I believe technically possible to have a submodule which is its
own super project, with and without recursion, but would be very
atypical, and would belong in the 'don't do that' category
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
On Fri, May 22, 2015 at 10:35 AM, Philip Oakley philipoak...@iee.org wrote:
From: Stefan Beller sbel...@google.com
On Fri, May 22, 2015 at 7:36 AM, Junio C Hamano gits...@pobox.com wrote:
Stefan Beller sbel...@google.com writes:
On Thu, May 21, 2015 at 1:03 PM, Philip Oakley philipoak...@iee.org
wrote:
+Submodules are not to be confused with remotes, which are meant
+mainly for branches of the same project;
This use of 'branches' didn't work for me. remotes are meant mainly
for
branches of the same project ?
The branch in the original is used in a much wider sense than
usual branch (i.e. ref/heads/ thing you have locally); it refers to
forks of the same project but with a bit of twist. When you say
repository A is a fork of the same project as my local repository,
you would give an impression that A is not the authoritative copy of
the project. But you can say my repository and that repository A
are branches of the same project, you give zero information as to
A's authoritativeness.
While this is correct, I think it is also confusing, because 'branch'
is a command which deals with local branches only in my perception
To deal with remote branches you need to use the commands
{remote, fetch, pull}.
So when someone mentions branch I need to think of local operations
in one repository and not on different distributed histories.
If we are having difficulties defining a remote here (its not defined in
gitglossary.txt anyway),
Now that we have a discussion on what remotes are, I'll send a patch for that
as well.
why not simply put a full stop (period) after the
Submodules are not to be confused with remotes., and bypass the problem,
avoiding digging the hole deeper.
I think we should dig deeper and point out the differences as it may
not be clear what
the differences are for new comers. Not digging deeper sounds to me like saying
'git frotz' is not to be confused with 'git bar' FULL STOP AND I
WONT TELL YOU WHY!
which is not helpful. (Why is the documentation pointing out there is
a difference to
that other command/concept, but not saying what is different?)
Submodules should not be confused with remote repositories, which
are
meant to track the same repository, just at another location; ...
I do not think this is a great improvement. You now conflated
repository to mean project in the latter half of the sentence,
while you are trying to explain what a remote repository is.
That's true.
Your copy of git.git is not the same repository as mine; they have
different histories. Both repositories are used to work on the same
project. submoules are not remotes, which are other repositories
of the same project, perhaps?
That makes sense.
If maybe that the feature we should pick on is the common root of the
development between the local and remote repository, and quite distinct for
the submodule. This allows remotes to be on the same machine, as well as
distant machines and server.
I don't think this is actually true for all remotes. Think of shallow clones
(they have no root or a different root) or even subtrees which are pulled
in via a remotes?
The main thing about remotes is not being here (as in part of this
repository. As you point out it can be nearby in the local fs or even on
another machine, or in the cloud)
It is I believe technically possible to have a submodule which is its own
super project, with and without recursion, but would be very atypical, and
would belong in the 'don't do that' category
--
To unsubscribe from this list: send the line unsubscribe git in
the body of a message to majord...@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
On Thu, May 21, 2015 at 10:24 AM, Junio C Hamano gits...@pobox.com wrote: Stefan Beller sbel...@google.com writes: Reorder the paragraphs such that the first short paragraph introduces the submodule concept, the second paragraph highlights the usage of the submodule command, the third paragraph giving background information, and finally the fourth paragraph discusing alternatives such as subtrees and remotes, which we don't want to be confused with. This ordering deepens the knowledge on submodules with each paragraph. First the basic questions like How/what will be answered, while the underlying concepts will be taught at a later time. Sounds good. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c25916..6c38c0d 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -25,35 +25,12 @@ SYNOPSIS DESCRIPTION --- -Submodules allow foreign repositories to be embedded within -a dedicated subdirectory of the source tree, always pointed -at a particular commit. +Submodules allow other repositories to be embedded within +a dedicated subdirectory of the source tree pointing +at a particular commit in the other repository. Not a new problem, but I can misread this as if it requires the top-level superproject to have one single dedicated directory D to house all the foreign projects under it, D/project1, D/project2, ... I agree, maybe we should reword the paragraphs themselves as well. Submodules allow you to keep another Git repository in a subdirectory of your repository. The other repository has its own history, which does not interfere with the history of the current repository. This can be used to have external dependencies such as libraries for example. -This command will manage the tree entries and contents of the -gitmodules file for you, as well as inspect the status of your -submodules and update them. +This command will manage the submodules for you, as well as +inspect the status of your submodules and update them. Not a new problem, but does the command really manage them for you? I view it more like You can use this command to manage, inspect and update the submodules. I agree. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
On Wed, May 20, 2015 at 04:11:57PM -0700, Stefan Beller wrote: It's better to start the man page with a description of what submodules actually are instead of saying what they are not. Reorder the paragraphs such that the first short paragraph introduces the submodule concept, the second paragraph highlights the usage of the submodule command, the third paragraph giving background information, and finally the fourth paragraph discusing alternatives such as subtrees and remotes, which we don't want to be confused with. This ordering deepens the knowledge on submodules with each paragraph. First the basic questions like How/what will be answered, while the underlying concepts will be taught at a later time. Making sure it is not confused with subtrees and remotes is not really enhancing knowledge of submodules itself, but rather painting the big picture of git concepts, so you could also argue to have it as the second paragraph. Personally I think this may confuse readers, specially newcomers though. Signed-off-by: Stefan Beller sbel...@google.com Looks good to me. Cheers Heiko -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
From: Stefan Beller sbel...@google.com It's better to start the man page with a description of what submodules actually are instead of saying what they are not. Reorder the paragraphs such that the first short paragraph introduces the submodule concept, the second paragraph highlights the usage of the submodule command, the third paragraph giving background information, and finally the fourth paragraph discusing alternatives such as subtrees and remotes, which we don't want to be confused with. This ordering deepens the knowledge on submodules with each paragraph. First the basic questions like How/what will be answered, while the underlying concepts will be taught at a later time. Making sure it is not confused with subtrees and remotes is not really enhancing knowledge of submodules itself, but rather painting the big picture of git concepts, so you could also argue to have it as the second paragraph. Personally I think this may confuse readers, specially newcomers though. Signed-off-by: Stefan Beller sbel...@google.com --- Documentation/git-submodule.txt | 54 - 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c25916..6c38c0d 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -25,35 +25,12 @@ SYNOPSIS DESCRIPTION --- -Submodules allow foreign repositories to be embedded within -a dedicated subdirectory of the source tree, always pointed -at a particular commit. +Submodules allow other repositories to be embedded within +a dedicated subdirectory of the source tree pointing +at a particular commit in the other repository. -They are not to be confused with remotes, which are meant mainly -for branches of the same project; submodules are meant for -different projects you would like to make part of your source tree, -while the history of the two projects still stays completely -independent and you cannot modify the contents of the submodule -from within the main project. -If you want to merge the project histories and want to treat the -aggregated whole as a single project from then on, you may want to -add a remote for the other project and use the 'subtree' merge strategy, -instead of treating the other project as a submodule. Directories -that come from both projects can be cloned and checked out as a whole -if you choose to go that route. - -Submodules are composed from a so-called `gitlink` tree entry -in the main repository that refers to a particular commit object -within the inner repository that is completely separate. -A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the -root of the source tree assigns a logical name to the submodule and -describes the default URL the submodule shall be cloned from. -The logical name can be used for overriding this URL within your -local repository configuration (see 'submodule init'). - -This command will manage the tree entries and contents of the -gitmodules file for you, as well as inspect the status of your -submodules and update them. +This command will manage the submodules for you, as well as +inspect the status of your submodules and update them. When adding a new submodule to the tree, the 'add' subcommand is to be used. However, when pulling a tree containing submodules, these will not be checked out by default; @@ -64,6 +41,27 @@ using the 'status' subcommand and get a detailed overview of the difference between the index and checkouts using the 'summary' subcommand. +Submodules are composed from a so-called `gitlink` tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the +root of the source tree assigns a logical name to the submodule and +describes the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see 'submodule init'). + +Submodules are not to be confused with remotes, which are meant +mainly for branches of the same project; This use of 'branches' didn't work for me. remotes are meant mainly for branches of the same project ? submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. -- Philip -- To unsubscribe from this
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
On Thu, May 21, 2015 at 1:03 PM, Philip Oakley philipoak...@iee.org wrote: +Submodules are not to be confused with remotes, which are meant +mainly for branches of the same project; This use of 'branches' didn't work for me. remotes are meant mainly for branches of the same project ? Maybe Submodules should not be confused with remote repositories, which are meant to track the same repository, just at another location; ... ? Though I'm not yet completely happy with that either. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH] submodule documentation: Reorder introductory paragraphs
Stefan Beller sbel...@google.com writes: Reorder the paragraphs such that the first short paragraph introduces the submodule concept, the second paragraph highlights the usage of the submodule command, the third paragraph giving background information, and finally the fourth paragraph discusing alternatives such as subtrees and remotes, which we don't want to be confused with. This ordering deepens the knowledge on submodules with each paragraph. First the basic questions like How/what will be answered, while the underlying concepts will be taught at a later time. Sounds good. diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c25916..6c38c0d 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -25,35 +25,12 @@ SYNOPSIS DESCRIPTION --- -Submodules allow foreign repositories to be embedded within -a dedicated subdirectory of the source tree, always pointed -at a particular commit. +Submodules allow other repositories to be embedded within +a dedicated subdirectory of the source tree pointing +at a particular commit in the other repository. Not a new problem, but I can misread this as if it requires the top-level superproject to have one single dedicated directory D to house all the foreign projects under it, D/project1, D/project2, ... -This command will manage the tree entries and contents of the -gitmodules file for you, as well as inspect the status of your -submodules and update them. +This command will manage the submodules for you, as well as +inspect the status of your submodules and update them. Not a new problem, but does the command really manage them for you? I view it more like You can use this command to manage, inspect and update the submodules. -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
[PATCH] submodule documentation: Reorder introductory paragraphs
It's better to start the man page with a description of what submodules actually are instead of saying what they are not. Reorder the paragraphs such that the first short paragraph introduces the submodule concept, the second paragraph highlights the usage of the submodule command, the third paragraph giving background information, and finally the fourth paragraph discusing alternatives such as subtrees and remotes, which we don't want to be confused with. This ordering deepens the knowledge on submodules with each paragraph. First the basic questions like How/what will be answered, while the underlying concepts will be taught at a later time. Making sure it is not confused with subtrees and remotes is not really enhancing knowledge of submodules itself, but rather painting the big picture of git concepts, so you could also argue to have it as the second paragraph. Personally I think this may confuse readers, specially newcomers though. Signed-off-by: Stefan Beller sbel...@google.com --- Documentation/git-submodule.txt | 54 - 1 file changed, 26 insertions(+), 28 deletions(-) diff --git a/Documentation/git-submodule.txt b/Documentation/git-submodule.txt index 2c25916..6c38c0d 100644 --- a/Documentation/git-submodule.txt +++ b/Documentation/git-submodule.txt @@ -25,35 +25,12 @@ SYNOPSIS DESCRIPTION --- -Submodules allow foreign repositories to be embedded within -a dedicated subdirectory of the source tree, always pointed -at a particular commit. +Submodules allow other repositories to be embedded within +a dedicated subdirectory of the source tree pointing +at a particular commit in the other repository. -They are not to be confused with remotes, which are meant mainly -for branches of the same project; submodules are meant for -different projects you would like to make part of your source tree, -while the history of the two projects still stays completely -independent and you cannot modify the contents of the submodule -from within the main project. -If you want to merge the project histories and want to treat the -aggregated whole as a single project from then on, you may want to -add a remote for the other project and use the 'subtree' merge strategy, -instead of treating the other project as a submodule. Directories -that come from both projects can be cloned and checked out as a whole -if you choose to go that route. - -Submodules are composed from a so-called `gitlink` tree entry -in the main repository that refers to a particular commit object -within the inner repository that is completely separate. -A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the -root of the source tree assigns a logical name to the submodule and -describes the default URL the submodule shall be cloned from. -The logical name can be used for overriding this URL within your -local repository configuration (see 'submodule init'). - -This command will manage the tree entries and contents of the -gitmodules file for you, as well as inspect the status of your -submodules and update them. +This command will manage the submodules for you, as well as +inspect the status of your submodules and update them. When adding a new submodule to the tree, the 'add' subcommand is to be used. However, when pulling a tree containing submodules, these will not be checked out by default; @@ -64,6 +41,27 @@ using the 'status' subcommand and get a detailed overview of the difference between the index and checkouts using the 'summary' subcommand. +Submodules are composed from a so-called `gitlink` tree entry +in the main repository that refers to a particular commit object +within the inner repository that is completely separate. +A record in the `.gitmodules` (see linkgit:gitmodules[5]) file at the +root of the source tree assigns a logical name to the submodule and +describes the default URL the submodule shall be cloned from. +The logical name can be used for overriding this URL within your +local repository configuration (see 'submodule init'). + +Submodules are not to be confused with remotes, which are meant +mainly for branches of the same project; submodules are meant for +different projects you would like to make part of your source tree, +while the history of the two projects still stays completely +independent and you cannot modify the contents of the submodule +from within the main project. +If you want to merge the project histories and want to treat the +aggregated whole as a single project from then on, you may want to +add a remote for the other project and use the 'subtree' merge strategy, +instead of treating the other project as a submodule. Directories +that come from both projects can be cloned and checked out as a whole +if you choose to go that route. COMMANDS -- 2.4.0.194.gc518059 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at
