Re: Tool renames? was Re: First stab at glossary
On Tue, 6 Sep 2005, Martin Langhoff wrote: Grep knows how to ignore binary files. That wasn't the _point_. The point is, naming things as being scripts is useful. Grep is just an example. Naming things as being .pl or .sh is _not_ useful. So with grep you can use -I, but what about doing things like em * when doing global renames (I use micro-emacs - em - as my editor). Again, em *-script actually works. The point being that if we have naming rules, make them USEFUL. *-script is useful - it works wonderfully well for git xxx (which knows to add -script), and it works wonderfully well for developers. Linus - 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
Re: Tool renames? was Re: First stab at glossary
Linus Torvalds [EMAIL PROTECTED] writes: The point is, naming things as being scripts is useful. Grep is just an example. Naming things as being .pl or .sh is _not_ useful. Sorry, but why not? - 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
Re: Tool renames? was Re: First stab at glossary
On 9/6/05, Linus Torvalds [EMAIL PROTECTED] wrote: That wasn't the _point_. Agreed - sorry I should have qualified my comment. I agree with having useful extensions for ease of development. And I agree with the suggestion of installing them with stripped extensions -- to extend the abstraction. OTOH... The point is, naming things as being scripts is useful. Grep is just an example. Naming things as being .pl or .sh is _not_ useful. Hrmmm. Not so convinced about that. There are good reasons to distinguish files with different internal syntax. Perhaps it's your C-bias but for script maintainers it isn't helpful to deal with -script prefixes. If a bash script is rewritten in C, it is a useful and meaningful change (from a developer perspective) that the file changes name. Both can live in the tree while the new one matures, running diffs or pickaxes will show one file created and another removed, instead of a very meaningless diff. The same applies if it is rewritten in Perl, or Python. IOW: Perl programmers are developers too ;-) cheers, martin - 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
Re: Tool renames? was Re: First stab at glossary
On Tue, 6 Sep 2005, Junio C Hamano wrote: Linus Torvalds [EMAIL PROTECTED] writes: The point is, naming things as being scripts is useful. Grep is just an example. Naming things as being .pl or .sh is _not_ useful. Sorry, but why not? What's the upside? I can point to one downside: git. That script right now is simple. If you rewrite git-cvsimport-script from shell to perl, it looks the same to git. Linus - 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
Re: Tool renames? was Re: First stab at glossary
Linus Torvalds [EMAIL PROTECTED] writes:
What's the upside?
I can point to one downside: git. That script right now is simple. If
you rewrite git-cvsimport-script from shell to perl, it looks the same to
git.
What I've been working on was to:
* have git-cvsimport.perl in the source
* install it as $(bindir)/git-cvsimport
* simplify 'git' (whose source is of course in 'git.sh') to
only do:
cmd=$1; shift; exec git-$cmd ${1+$@}
Naturally, the rewrite of git-cvsimport in shell or C would look
the same to git.
One potential downside (for people who consider this a downside)
is that you cannot easily run uninstalled, but you already
cannot run tools/git-applymbox and git-cherry-pick uninstalled
anyway, and I do not think it is such a big deal.
-
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
Re: Tool renames? was Re: First stab at glossary
Junio C Hamano [EMAIL PROTECTED] writes: Linus Torvalds [EMAIL PROTECTED] writes: What's the upside? I can point to one downside: git. That script right now is simple. If you rewrite git-cvsimport-script from shell to perl, it looks the same to git. What I've been working on was to: * have git-cvsimport.perl in the source * install it as $(bindir)/git-cvsimport That was what I suggested too, although I don't really care if it's called .perl or -script in the source. By the way, I'm not sure how the 'git' script is supposed to be used. I know that if there is a git-foo-script file in your path, you can run it as 'git foo'. But what about e.g. git-init-db? You can run that as 'git init-db' today. And 'git read-cache' should work too. And 'git ls-files', and 'git rev-parse', and 'git merge-one-file' and 'git sh-setup-script' in decreasing order of usefulness... But running 'git' without arguments only list the -script commands as available. -- David Kågedal - 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
Re: Tool renames? was Re: First stab at glossary
Horst von Brand wrote: Junio C Hamano [EMAIL PROTECTED] wrote: Tim Ottinger [EMAIL PROTECTED] writes: git-update-cache for instance? I am not sure which 'cache' commands need to be 'index' now. Logically you are right, but I suspect that may not fly well in practice. Too many of us have already got our fingers wired to type cache, and the glossary is there to describe both cache andindex. I'd vote for cleaning it up /now/. Sure, it will hurt, but if you let time go by and do it later, it will hurt much more. Pre-1.0 is the last chance, AFAICS. I guess it all depends on whether your target audience is already using it an happy with how it is, or whether your target audience is yet to be reached. Is git growing? Do we expect to suddenly find git upside down, where there are a few old-timers awash in a sea of newbies? Do we care? If you care, and git is growing, then probably it makes sense to choose the greatest good for the greatest number, I guess. Personally, I'm a newbie and I find the command set confusing and hard to internalize for reasons mostly dealing with naming, but also because I don't have 6 months shared history with all of you. I have to learn it partly from docs and partly through folklore gleaned from the list (which moves pretty quickly). Maybe that's just complaining, but maybe it is pointing out a weakness that's correctable. -- ... either 'way ahead of the game, or 'way out in left field. - 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
Re: Tool renames? was Re: First stab at glossary
By the way, I'm not sure how the 'git' script is supposed to be used. I know that if there is a git-foo-script file in your path, you can run it as 'git foo'. But what about e.g. git-init-db? You can run that as 'git init-db' today. And 'git read-cache' should work too. And 'git ls-files', and 'git rev-parse', and 'git merge-one-file' and 'git sh-setup-script' in decreasing order of usefulness... But running 'git' without arguments only list the -script commands as available. You are correct. I think 'git' showing only *-script was done as an attempt to give a list of Porcelainish commands, excluding the core commands that people are not supposed to be typing from the command line. It so happened that all of the Porcelainish commands were scripts. But what Linus wants *-script to mean is editability in the source tree (his grep and em examples). The command being Porcelainish and the command being implemented as a script tend to have strong correlations, but in principle they are orthogonal. As you mention, 'git merge-one-file' is not really useful standalone, neither is 'git sh-setup'. On the other hand, 'git fsck-cache' is. My proposal to have git-archimport.perl in the source tree and install it as $(bindir)/git-archimport solves the editability issues (sorry, Linus, you will have to say em *.sh *.perl instead of em *-script if we did this) and simplifies the first half of the 'git' wrapper (it just needs to attempt running git-$1), but does not help what the latter half of 'git' wrapper does (to give you the list of Porcelainish commands). To make 'git' wrapper produce useful 'list of subcommands', we need to come up with a list of Porcelainish commands, be they written in C or sh or Perl, and tell 'git' about that list. Current implementation cheats by assuming everything that ends with *-script are such, but it does not have to stay that way. I'd nominate all $(SCRIPTS) in Makefile and tools/Makefile except *1*, plus *2* as the list of subcommands 'git' wrapper would show. List *1*: implemented as script but not Porcelainish. git git-merge-one-file-script git-sh-setup-script List *2*: implemented in C but Porcelainish. git-init-db git-fsck-cache git-get-tar-commit-id git-apply git-patch-id git-pack-objects git-show-branch - 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
Re: Tool renames? was Re: First stab at glossary
On Mon, 5 Sep 2005, David Kågedal wrote: But to the users (like myself), there's no point in naming it by whether it's a script or a binary. So? There's no downside. To you, as a user, you never see the -script ending anyway. You'd never type it out, or you're already doing something wrong. So to users it doesn't matter, and to developers it _does_ matter (and calling them .pl or .sh or something would be _bad_), why not please the developers? So your argument that it makes it easier for git developers to work with the source doesn't help the user. It doesn't _help_ the user, but since it doesn't hurt him either, why the hell would we even _care_ about the user? Linus - 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
Re: Tool renames? was Re: First stab at glossary
Linus Torvalds [EMAIL PROTECTED] writes: On Mon, 5 Sep 2005, David Kågedal wrote: But to the users (like myself), there's no point in naming it by whether it's a script or a binary. So? There's no downside. To you, as a user, you never see the -script ending anyway. You'd never type it out, or you're already doing something wrong. Then I'm doing something wrong. And I'm pretty sure others are too. If I'm not supposed to see the -script ending, then don't install it in my $PATH. Until someone (possibly myself) writes some zsh completion code to handle git sub command, I will continue to hit TAB and see all those names. Furthermore, the man page for git clone is called git-clone-script(1). And the -script suffix appears inside the documentation in various places. I see it in howtos and log messages. And the git-merge-one-file-script script is supposed to be used in a way where I have to supply the long name. Etc. If the -script part is supposed to be hidden from me, why do I keep seeing it everywhere I turn? So to users it doesn't matter, and to developers it _does_ matter (and calling them .pl or .sh or something would be _bad_), why not please the developers? I'm not suggesting we'd call them .pl or .sh. -- David Kågedal - 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
Re: Tool renames? was Re: First stab at glossary
Linus Torvalds [EMAIL PROTECTED] writes: ... and I don't see _any_ point to naming by what _kind_ of interpreter you use. Why would _anybody_ care whether something is written in perl vs shell? One possibility that comes to mind is to again help developers who use an editor that is syntax-aware and looks *only* at filename suffix to figure out which language syntax to use (Emacs is not one of them -- it knows how to read #! line). Another is, although we do not currently do it, to make the Makefile simpler if/when we start to do the interpreter line munging (#!/usr/bin/perl - #!/usr/local/bin/perl) before install time. - 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
Re: Tool renames? was Re: First stab at glossary
On 9/6/05, Linus Torvalds [EMAIL PROTECTED] wrote: Grepping for strings. For example, when renaming a binary, the sane way to check that you fixed all users right now is grep old-binary-name *.c *.h *-scripts and you catch all users. Grep knows how to ignore binary files. Try: grep -I git-commit * cheers, martin - 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
Re: Tool renames? was Re: First stab at glossary
Junio C Hamano [EMAIL PROTECTED] wrote: I said: I'll draw up a strawman tonight unless somebody else does it first. [...] 3. Non-binaries are called '*-scripts'. In earlier discussions some people seem to like the distinction between *-script and others; I did not particularly like it, but I am throwing this in for discussion. I for one think this makes the command name dependent on a non-essential implementation detail, so -script should go. -- Dr. Horst H. von Brand User #22616 counter.li.org Departamento de Informatica Fono: +56 32 654431 Universidad Tecnica Federico Santa Maria +56 32 654239 Casilla 110-V, Valparaiso, ChileFax: +56 32 797513 - 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
Re: Tool renames? was Re: First stab at glossary
Horst von Brand [EMAIL PROTECTED] writes:
3. Non-binaries are called '*-scripts'.
In earlier discussions some people seem to like the
distinction between *-script and others; I did not
particularly like it, but I am throwing this in for
discussion.
I for one think this makes the command name dependent on a non-essential
implementation detail, so -script should go.
I had the same opinion. The counter-argument people raised when
this topic came up on the list was that it would help grepping
in the source tree.
I'm tempted to suggest doing something along these lines:
- Rename things that are implemented in shell from *-script to
*.sh, and perl to *.perl in the source tree;
- Install them without .{sh,perl} suffix.
Once this is done, the users nor the 'git' wrapper do not have
to deal with *-script.
Comments?
-
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
Re: Tool renames? was Re: First stab at glossary
Peter Williams [EMAIL PROTECTED] writes: *.pl is what is usually used for perl scripts. My recollection may be faulty, but '*.pl' was meant to be used for older Perl libraries back in perl4 days, and the standalone scripts are to be named '*.perl' but many people made the mistake of naming them '*.pl'. - 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
Re: Tool renames? was Re: First stab at glossary
I said: I'll draw up a strawman tonight unless somebody else does it first. 1. Say 'index' when you are tempted to say 'cache'. git-checkout-cache git-checkout-index git-convert-cache git-convert-index git-diff-cache git-diff-index git-fsck-cache git-fsck-index git-merge-cache git-merge-index git-update-cachegit-update-index 2. The act of combining two or more heads is called 'merging'; fetching immediately followed by merging is called 'pulling'. git-resolve-script git-merge-script The commit walkers are called *-pull, but this is probably confusing. They are not pulling. git-http-pull git-http-walk git-local-pull git-local-walk git-ssh-pullgit-ssh-walk 3. Non-binaries are called '*-scripts'. In earlier discussions some people seem to like the distinction between *-script and others; I did not particularly like it, but I am throwing this in for discussion. git-applymbox git-applymbox-script git-applypatch git-applypatch-script git-cherry git-cherry-script git-shortloggit-shortlog-script git-whatchanged git-whatchanged-script 4. To be removed shortly. git-clone-dumb-http should be folded into git-clone-script - 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
Re: Tool renames? was Re: First stab at glossary
On Thu, 1 Sep 2005, Junio C Hamano wrote: Tim Ottinger [EMAIL PROTECTED] writes: git-update-cache for instance? I am not sure which 'cache' commands need to be 'index' now. Logically you are right, but I suspect that may not fly well in practice. Too many of us have already got our fingers wired to type cache, and the glossary is there to describe both cache and index. My vote's for changing the official names, but keeping symlinks for the old names. As far as I know, there aren't any actual conflicts, and we might as well have new users pick up the logical names. I particularly think git merge would be really good to have. -Daniel *This .sig left intentionally blank* - 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
Re: Tool renames? was Re: First stab at glossary
Junio C Hamano wrote: Tim Ottinger [EMAIL PROTECTED] writes: So when this gets all settled, will we see a lot of tool renaming? I personally do not see it coming. Any particular one you have in mind? git-update-cache for instance? I am not sure which 'cache' commands need to be 'index' now. -- ... either 'way ahead of the game, or 'way out in left field. - 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
Re: Tool renames? was Re: First stab at glossary
Tim Ottinger [EMAIL PROTECTED] writes: git-update-cache for instance? I am not sure which 'cache' commands need to be 'index' now. Logically you are right, but I suspect that may not fly well in practice. Too many of us have already got our fingers wired to type cache, and the glossary is there to describe both cache and index. - 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
Tool renames? was Re: First stab at glossary
So when this gets all settled, will we see a lot of tool renaming? While it would cause me and my team some personal effort (we have a special-purpose porcelain), it would be welcome to have a lexicon that is sane and consistent, and in tune with all the documentation. Others may feel differently, I understand. -- ... either 'way ahead of the game, or 'way out in left field. - 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
Re: Tool renames? was Re: First stab at glossary
Tim Ottinger [EMAIL PROTECTED] writes: So when this gets all settled, will we see a lot of tool renaming? I personally do not see it coming. Any particular one you have in mind? - 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
First stab at glossary
Hi, long, long time. Here´s my first stab at the glossary, attached the alphabetically sorted, asciidoc marked up txt file (Comments? Suggestions? Pizzas?): object:: The unit of storage in GIT. It is uniquely identified by the SHA1 of its contents. Consequently, an object can not be changed. SHA1:: A 20-byte sequence (or 41-byte file containing the hex representation and a newline). It is calculated from the contents of an object by the Secure Hash Algorithm 1. object database:: Stores a set of objects, and an individial object is identified by its SHA1 (its ref). The objects are either stored as single files, or live inside of packs. object name:: Synonym for SHA1. blob object:: Untyped object, i.e. the contents of a file. tree object:: An object containing a list of blob and/or tree objects. (A tree usually corresponds to a directory without subdirectories). tree:: Either a working tree, or a tree object together with the dependent blob and tree objects (i.e. a stored representation of a working tree). cache:: A collection of files whose contents are stored as objects. The cache is a stored version of your working tree. Well, can also contain a second, and even a third version of a working tree, which are used when merging. cache entry:: The information regarding a particular file, stored in the index. A cache entry can be unmerged, if a merge was started, but not yet finished (i.e. if the cache contains multiple versions of that file). index:: Contains information about the cache contents, in particular timestamps and mode flags (stat information) for the files stored in the cache. An unmerged index is an index which contains unmerged cache entries. working tree:: The set of files and directories currently being worked on. Think ls -laR directory:: The list you get with ls :-) checkout:: The action of updating the working tree to a revision which was stored in the object database. revision:: A particular state of files and directories which was stored in the object database. It is referenced by a commit object. commit:: The action of storing the current state of the cache in the object database. The result is a revision. commit object:: An object which contains the information about a particular revision, such as parents, committer, author, date and the tree object which corresponds to the top directory of the stored revision. changeset:: BitKeeper/cvsps speak for commit. Since git does not store changes, but states, it really does not make sense to use the term changesets with git. ent:: Favorite synonym to tree-ish by some total geeks. clean:: A working tree is clean, if it corresponds to the revision referenced by the current head. dirty:: A working tree is said to be dirty if it contains modifications which have not been committed to the current branch. head:: The top of a branch. It contains a ref to the corresponding commit object. branch:: A non-cyclical graph of revisions, i.e. the complete history of a particular revision, which does not (yet) have children, which is called the branch head. The branch heads are stored in $GIT_DIR/refs/heads/. ref:: A 40-byte hex representation of a SHA1 pointing to a particular object. These are stored in $GIT_DIR/refs/. head ref:: A ref pointing to a head. Often, this is abbreviated to head. Head refs are stored in $GIT_DIR/refs/heads/. tree-ish:: A ref pointing to either a commit object, a tree object, or a tag object pointing to a commit or tree object. tag object:: An object containing a ref pointing to another object. It can contain a (PGP) signature, in which case it is called signed tag object. tag:: A ref pointing to a tag or commit object. In contrast to a head, a tag is not changed by a commit. Tags (not tag objects) are stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with a Lisp tag (which is called object type in git's context). merge:: To merge branches means to try to accumulate the changes since a common ancestor and apply them to the first branch. An automatic merge uses heuristics to accomplish that. Evidently, an automatic merge can fail. resolve:: The action of fixing up manually what a failed automatic merge left behind. repository:: A collection of refs together with an object database containing all objects, which are reachable from the refs. A repository can share an object database
Re: First stab at glossary
On Wed, 17 Aug 2005, Johannes Schindelin wrote: Hi, long, long time. Here?s my first stab at the glossary, attached the alphabetically sorted, asciidoc marked up txt file (Comments? Suggestions? Pizzas?): object:: The unit of storage in GIT. It is uniquely identified by the SHA1 of its contents. Consequently, an object can not be changed. SHA1:: A 20-byte sequence (or 41-byte file containing the hex representation and a newline). It is calculated from the contents of an object by the Secure Hash Algorithm 1. It's also often 40-character string (with whatever termination) in places like commit objects, tag objects, command-line arguments, listings, and so forth. object database:: Stores a set of objects, and an individial object is identified by its SHA1 (its ref). The objects are either stored as single files, or live inside of packs. object name:: Synonym for SHA1. Have we killed the use of the third term hash for this? I'd say that object name is the standard term, and SHA1 is a nickname, if only because object name is more descriptive of the particular use of the term. blob object:: Untyped object, i.e. the contents of a file. This i.e. should be e.g., since symlink targets are also stored as blobs, and any other bulk data stored by itself would be. (IIRC, Junio has a tagged blob to hold his public key, for example) tree object:: An object containing a list of blob and/or tree objects. (A tree usually corresponds to a directory without subdirectories). tree:: Either a working tree, or a tree object together with the dependent blob and tree objects (i.e. a stored representation of a working tree). cache:: A collection of files whose contents are stored as objects. The cache is a stored version of your working tree. Well, can also contain a second, and even a third version of a working tree, which are used when merging. cache entry:: The information regarding a particular file, stored in the index. A cache entry can be unmerged, if a merge was started, but not yet finished (i.e. if the cache contains multiple versions of that file). index:: Contains information about the cache contents, in particular timestamps and mode flags (stat information) for the files stored in the cache. An unmerged index is an index which contains unmerged cache entries. I think we might want to entirely kill the cache term, and talk only about the index and index entries. Of course, a bunch of the code will have to be renamed to make this completely successful, but we could change the glossary and documentation, and mention cache and cache entry as old names for index and index entry respectively. working tree:: The set of files and directories currently being worked on. Think ls -laR This is where the data is actually in the filesystem, and you can edit and compile it (as opposed to a tree object or the index, which semantically have the same contents, but aren't presented in the filesystem that way). directory:: The list you get with ls :-) checkout:: The action of updating the working tree to a revision which was stored in the object database. Move after revision? revision:: A particular state of files and directories which was stored in the object database. It is referenced by a commit object. commit:: The action of storing the current state of the cache in the object database. The result is a revision. commit object:: An object which contains the information about a particular revision, such as parents, committer, author, date and the tree object which corresponds to the top directory of the stored revision. Move parent around here. changeset:: BitKeeper/cvsps speak for commit. Since git does not store changes, but states, it really does not make sense to use the term changesets with git. ent:: Favorite synonym to tree-ish by some total geeks. Move after tree-ish. head:: The top of a branch. It contains a ref to the corresponding commit object. branch:: A non-cyclical graph of revisions, i.e. the complete history of a particular revision, which does not (yet) have children, which is called the branch head. The branch heads are stored in $GIT_DIR/refs/heads/. A branch head might have children, if they're in another branch. (E.g., I pull mainline, make a new branch based on it, and commit a change; the head of mainline is still a branch head, even though it's the parent of my new commit, because my new commit isn't in mainline.) ref:: A 40-byte hex representation of a SHA1 pointing to a particular object. These are stored in $GIT_DIR/refs/. head ref:: A ref pointing to a head. Often
Re: First stab at glossary
Hi, On Wed, 17 Aug 2005, Daniel Barkalow wrote: On Wed, 17 Aug 2005, Johannes Schindelin wrote: SHA1:: A 20-byte sequence (or 41-byte file containing the hex representation and a newline). It is calculated from the contents of an object by the Secure Hash Algorithm 1. It's also often 40-character string (with whatever termination) in places like commit objects, tag objects, command-line arguments, listings, and so forth. Okay. object name:: Synonym for SHA1. Have we killed the use of the third term hash for this? I'd say that object name is the standard term, and SHA1 is a nickname, if only because object name is more descriptive of the particular use of the term. Okay for hash. What is the consensus on object name being more standard than SHA1? blob object:: Untyped object, i.e. the contents of a file. This i.e. should be e.g., since symlink targets are also stored as blobs, and any other bulk data stored by itself would be. (IIRC, Junio has a tagged blob to hold his public key, for example) Agree. I think we might want to entirely kill the cache term, and talk only about the index and index entries. Of course, a bunch of the code will have to be renamed to make this completely successful, but we could change the glossary and documentation, and mention cache and cache entry as old names for index and index entry respectively. For me, index is just the file named index (holding stat data and a ref for each cache entry). That is why I say an index contains cache entries, not index entries (wee, that sounds wrong :-). working tree:: The set of files and directories currently being worked on. Think ls -laR This is where the data is actually in the filesystem, and you can edit and compile it (as opposed to a tree object or the index, which semantically have the same contents, but aren't presented in the filesystem that way). Maybe I was too cautious. Linus very new idea was to think of the lowest level of an SCM as a file system. But I did not want to mention that. Thinking of it again, maybe I should. checkout:: Move after revision? Ultimately, the glossary terms will be sorted alphabetically. If you look at the file attached to my original mail, this is already sorted and marked up using asciidoc. However, I wanted you and the list to understand how I grouped terms. The asciidoc'ed file is generated by a perl script. Move parent around here. See above. Move after tree-ish. Ditto. branch:: A non-cyclical graph of revisions, i.e. the complete history of a particular revision, which does not (yet) have children, which is called the branch head. The branch heads are stored in $GIT_DIR/refs/heads/. A branch head might have children, if they're in another branch. (E.g., I pull mainline, make a new branch based on it, and commit a change; the head of mainline is still a branch head, even though it's the parent of my new commit, because my new commit isn't in mainline.) Well noted! I'll just delete that part. tag:: A ref pointing to a tag or commit object. In contrast to a head, a tag is not changed by a commit. Tags (not tag objects) are stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with a Lisp tag (which is called object type in git's context). As above, only the head for the branch being committed to is changed by a commit. A tag, not being the head of a branch, is therefore never changed by a commit. I tried to say that. resolve:: The action of fixing up manually what a failed automatic merge left behind. Resolve is also used for the automatic case (e.g., in git-resolve-script, which goes from having two commits and a message to having a new commit). I'm not sure what the distinction is supposed to be. I did not like that naming anyway. In reality, git-resolve-script does not resolve anything, but it merges two revisions, possibly leaving something to resolve. Ciao, Dscho - 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
Re: First stab at glossary
Johannes Schindelin [EMAIL PROTECTED] writes: Okay for hash. What is the consensus on object name being more standard than SHA1? The tutorial uses the term object name, so does README (implicitly, by saying All objects are named by their content, which is approximated by the SHA1 hash of the object itself). I think it is pretty safe to assume the list agrees with this term. For me, index is just the file named index (holding stat data and a ref for each cache entry). That is why I say an index contains cache entries, not index entries (wee, that sounds wrong :-). I think Linus already commented on using index file and index entries as the canonical terms. It would be a good idea to mention cache as a historical synonym in the documentation, so that we do not have to rename the symbols in the code. Ultimately, the glossary terms will be sorted alphabetically. If you look at the file attached to my original mail, this is already sorted and marked up using asciidoc. However, I wanted you and the list to understand how I grouped terms. The asciidoc'ed file is generated by a perl script. Then we should put the text version under Documentation, along with that script and a Makefile entry to do asciidoc and another to go to html. No rush for the script and Makefile entries, but it would make things easier to manage if we put the text version in the tree soonish. I've pushed out the one from your original First stab message. branch:: A non-cyclical graph of revisions, i.e. the complete history of a particular revision, which does not (yet) have children, which is called the branch head. The branch heads are stored in $GIT_DIR/refs/heads/. I wonder if there is a math term for a non-cyclical graph that has a single greater than anything else in the graph node (but not necessarily a single but possibly more lesser than anything else in the graph nodes)? tag:: A ref pointing to a tag or commit object. In contrast to a head, a tag is not changed by a commit. Tags (not tag objects) are stored in $GIT_DIR/refs/tags/. A git tag has nothing to do with a Lisp tag (which is called object type in git's context). I think this is good already, but maybe mention why you would use a tag in a sentence? Most typically used to mark a particular point in the commit ancestry chain, or something. resolve:: The action of fixing up manually what a failed automatic merge left behind. Resolve is also used for the automatic case (e.g., in git-resolve-script, which goes from having two commits and a message to having a new commit). I'm not sure what the distinction is supposed to be. I did not like that naming anyway. In reality, git-resolve-script does not resolve anything, but it merges two revisions, possibly leaving something to resolve. I am sure this would break people's script, but I am not against renaming git-resolve-script to say git-merge-script. Anyway, thanks for doing this less-fun and not-so-glorious job. - 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
Re: First stab at glossary
Hi, On Wed, 17 Aug 2005, Daniel Barkalow wrote: On Wed, 17 Aug 2005, Johannes Schindelin wrote: On Wed, 17 Aug 2005, Daniel Barkalow wrote: [...] Okay for hash. I think we only need at most two names for this, so this is more a matter of fixing old usage than documenting it. It's short enough to keep it in the glossary _and_ fix the old documentation. [blabla] index [blable] cache [bliblo] Well, it often contains information not present anywhere else (the status of a merge; the set of files being committed, added, or removed), so it isn't really a cache at all. Okay, okay. I stand corrected. Maybe I was too cautious. Linus very new idea was to think of the lowest level of an SCM as a file system. But I did not want to mention that. Thinking of it again, maybe I should. You probably don't need to mention that tree objects and index files can be thought of as filesystems, but you should specify that the working tree really is in the Unix filesystem, in case people have heard of the idea. It should be clear to say 'You can cd there and ls to list your files.', rather than 'Think ls -laR' which makes my think of the output, which is like the output from git-ls-files. How about this: working tree:: The set of files and directories currently being worked on, i.e. you can work in your working tree without using git at all. checkout:: Move after revision? Ultimately, the glossary terms will be sorted alphabetically. If you look at the file attached to my original mail, this is already sorted and marked up using asciidoc. However, I wanted you and the list to understand how I grouped terms. The asciidoc'ed file is generated by a perl script. Ah, okay. Sorry, I attributed these moving suggestions to the large and angry SCM, while those were your comments. Since Junio decided to keep the topic ordered form in his repository, I moved them around according to your mail. resolve:: The action of fixing up manually what a failed automatic merge left behind. Resolve is also used for the automatic case (e.g., in git-resolve-script, which goes from having two commits and a message to having a new commit). I'm not sure what the distinction is supposed to be. I did not like that naming anyway. In reality, git-resolve-script does not resolve anything, but it merges two revisions, possibly leaving something to resolve. Right; I think we should change the name of the script. How many users are there? Probably many call git-pull-script anyway, right? Ciao, Dscho - 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
