Re: svn versus git

Hello,

With all the discussion about user interface difficulties, I started to write a comparison with subversion document. (I was assuming that people find subversion easy). As much as I love git, I was expecting to find that it's hard to use interface would have subversion as the clear winner. I was hoping that would then give guidance as to what could be fixed in git.

I was surprised, therefore, to find that in each case I was finding that git was the winner.

This is only the first draft, so it's not very pretty; given that I now think it's fairly pointless, I doubt very much that there will be a second draft. However, before I consign it to the waste bin; I thought I'd share what I had in case someone here had a use for it.

Executive summary: for the subset of features that git supplies that would 
make it a subversion replacement; the UI for git is broadly compatible and 
mostly better.  The areas that make git look scary are:
 - git-clone
 - git-checkout
 - git-help
 - "svn cat" is missing from git
 - git-ls-tree
 - git-fsck-objects/git-repack/git-prune
 - "svn revert" is missing from git

As always, please take the following with liberal amounts of IMHO.

--------------------------------- Subversion Versus Git ===================== Andy Parkins <andyparkins@gmail.com>

Introduction ------------

Git is often accused of having a difficult user interface. I had imagined that was the case too. I decided to write this comparison to show the areas for which a simple version control system (like subversion) had got the user interface right, and git had it wrong.

I was surprised to find that the areas of difficulty were a lot fewer than I had expected. There is no reason why a user familiar with subversion couldn't quickly cope with git's commands. I realised I had been looking at Subversion through rose-tinted glasses. For the set of features that Subversion supports, git is just as easy to use - if not easier.

Note that this comparison is not of features, but of interface. Git easily wins in terms of features. When it comes to using the more advanced features of git, for which there is no Subversion equivalent, then obviously there will be things to be learned. This comparison however is limited to the subset of features of git that would make it as near an equivalent to subversion as possible.

Comparison ----------

svn add:: Put files and directories under version control, scheduling them for addition to repository. They will be added in next commit. This doesn't really add anything, it just schedules. git add:: Add files to the index file. This command does not simply schedule. It takes the current contents of the file and copies it to the git staging area.

The git index makes this command more complicated for git; however git is using the verb "add" more correctly. In the subversion case, nothing is actually added to a repository, it is merely scheduled for addition. Although one could argue that by its nature, everything in subversion is merely scheduling the action. Subversion being inherently simpler, makes this easier to understand for the subversion user.

svn blame:: Output the content of specified files or URLs with revision and author information inline. git blame:: Show what revision and author last modified each line of a file.

This one is a draw. However, in terms of output, git is signficantly better, it is much more intelligent about renames and copies and is much faster.

svn cat:: Output the contents of specified files or URLs. Optionally at a specific revision. git cat-file -p $(git-ls-tree $REV $file | cut -d " " -f 3 | cut -f 1):: git-ls-tree lists the object ID for $file in revision $REV, this is cut out of the output and used as an argument to git-cat-file, which should really be called git-cat-object, and simply dumps that object to stdout.

Subversion wins. This is a distinctly non-user friendly way of reading a file.

svn checkout:: Checkout a working copy from a repository. You may check out an arbitrary revision. git clone:: git checkout:: Git, of course, is different from subversion, as the whole repository is always available. git-checkout is nearest in concept to svn-checkout though. It changes the current working directory to a particular branch. You may not checkout an arbitrary revision. git-clone might also be considered as an svn checkout analog. However,

Subversion wins. The output from Subversion's checkout is clear. The output from git-clone gives output that is only understandable by someone familiar with git internals.

svn cleanup:: Recursively clean up the working copy, removing locks, resuming unfinished operations, etc. git fsck-objects:: git prune:: git repack:: Check the repository for consistency, remove unreferenced objects, or recompress existing objects.

They don't really serve the exact same purpose, but they are all maintenance commands.

Subversion wins, as it only has one command and you don't need to understand the repository in order to understand what its doing.

svn commit:: Pushes changes to the upstream respository from your working copy. git commit -a:: Saves changes to the working copy as a new revision in the local repository.

The need for "-a" (or not) because of git's staging area (the index) here makes it more confusing than svn-commit for new users. However, the ability to do "git --amend" more than makes up for it. Fixing a typo in your last log message is difficult in subversion. Also, git's commit message template is much better: both uses the output of their status commands which is far clearer in git than in Subversion.

Git wins.

svn copy:: Duplicate something in working copy or repository, remembering history. cp A B; git add B:: Git doesn't have a direct equivalent of svn copy. It's arguable whether it needs it once the user knows they can git-add so easily.

Git wins. Git's ability to detect copies after-the-fact, mean that a git-copy isn't necessary.

svn delete:: Remove files and directories from version control. git rm:: Remove files from the working copy and the staging area.

Git wins. Git wins this because it doesn't need the git-rm at all. It notices when a file has been removed anyway in git-commit -a; so for this comparison, we can say that git-rm is not needed. For more complex cases, were a user wants to remove a file from version control, but not from disk, git-rm might be needed.

svn diff:: Display the differences between two paths. Defaults to showing the differences between HEAD and the working copy. git diff:: As for svn; but is arguably more powerful. It also has the distinct advantage that it colourises its output, making it much easier to read.

Git wins. More powerful functionality available, but its default output is fine as it is.

svn export:: Create an unversioned copy of a tree. git archive:: Creates an archive of the files in the named tree.

Git wins. It can make zip/tar directly and add directory prefixes should you want them. It could perhaps be a modicum easier if it had a default output format so that "git-archive HEAD" would do something.

svn help:: git help:: Both of these operate in the same way, so this one will be judged on utility of the output.

Subversion wins. The output from subversion often fits on a single screen, and is merely there to give a reminder of what each option does. git help simply forwards the user to a man page; which is very thorough, but usually more than you need for a quick reference.

svn import:: Commit an unversioned file or tree into the repository. git-init-db; git-add:: Git doesn't import external trees. Mainly because it doesn't need to. Any directory can be quickly turned into a repository because git-init-db and git-add are so fast. It can easily be turned back because git only keeps one special directory (".git") at the top of the working tree whereas subversion keeps one ".svn" directory per working directory. Conversely, there is no way in subversion to adopt an existing directory structure. It must be imported then checked out somewhere else.

Git wins. It's fast and simple. There is only the most minimal change to the users working tree.

svn info:: Display information about a local or remote item. [no git equivalent]:: Apart from manually running git-log, git-show, git-diff, etc. There is no way to get the simple summary that subversion provides about a given item.

svn list:: List directory entries in the repository. Showing an arbitrary revision if wanted. git ls-tree:: Lists the content of a tree object.

Subversion wins. The output of git-ls-tree is not user friendly; it requires some understanding of git internals.

svn lock:: svn unlock:: Lock working copy paths in the repository so that no other user can commit changes to them. [no git equivalent]:: Git can't do this; nor should it. Your repository is your own so there is no point in locking any part of it.

Git wins. Being distributed makes this function unnecessary in git. This makes one less command to learn.

svn log:: Show the log messages for a set of revision(s) and/or file(s). git log:: Show commit logs.

Git wins. The log command is equally as simple to use, but git supports more output formats (--pretty=online I find particularly useful). It also colours it and formats it for much easier viewing. It can also accept much more human-convenient filters (git log --since="2 weeks ago").

svn merge:: Apply the differences between two sources to a working copy path. git pull:: Pull and merge from another repository or a local branch.

It could be argued that "pull" is a bad name for this command. Apart from that however, git-pull is significantly easier to use than svn merge. It's output isn't as easy to understand, as it dumps loads of confusing information to the user.

Git wins. Once you've used it, it's nowhere near as terrifying to use, because it can be easily undone. It's harder to do damage because git tracks merges whereas svn doesn't. It's better at merging. You will spend a good five minutes thinking about what you must type for an svn-merge. git-pull is a no-brainer.

svn mkdir:: Create a new directory under version control. [no git equivalent]:: Git doesn't track directories, so doesn't need this command. Simply adding content that is in a subdirectory is sufficient.

Git wins. It does the right thing for you and you needn't remember to wrap your "mkdir"s with your VCS. Also, one-less-command.

svn move:: Move and/or rename something in working copy or repository. git-mv:: Move or rename a file, directory or symlink.

Git wins. The two are equivalent except that git can do multiple moves in one command, just like normal "mv". So "git mv src/* newsrc/" works while "svn mv src/* newsrc/" doesn't. Additionally, if you forget to do moves with git and instead use the command line, you can easily use "update-index" to tell git about the move after the fact. In subversion you have to undo all the moves and do them again with subversion. This makes it inconvenient to use tools like "rename" to do regexp moves.

svn resolved:: Remove 'conflicted' state on working copy files or directories. git update-index:: git checkout:: Git doesn't have a direct "resolved"; after you fix conflicts, you push the changes into the staging area with "git-update-index". Alternatively you can simply accept the version in HEAD by checking out that version.

Draw. "svn-resolved" is rubbish, as it doesn't do any checks, it just removes the conflict markers. Git could do with something that makes life easier than understanding the index.

svn revert:: Restore pristine working copy file (undo most local edits). git reset --hard:: Reset the repository to an arbitrary point in the past, updating the working copy as well. git checkout -f HEAD <file>:: Checks out <file> from HEAD, forcing an overwrite of any working directory changes to that file.

Draw. There is no easy way to undo changes that have already been committed to a subversion repository, so git would win. However, it's uncomfortable to revert a single file using checkout.

svn status:: Print the status of working copy files and directories. git status:: Show working tree status.

Git wins. Git's status output is colorised and doesn't rely on you remembering single letter codes for file status. Instead is arranges the changes in sections and describes the status in English. It shows renames clearly, and sorts the file list instead of leaving it in a random order (which makes it difficult to find particular files).

svn switch:: Update the working copy to a different URL. [no git equivalent]:: git is distributed and can fetch from any number of remote repositories. The URL can be typed on the command line of git-fetch, or can be given a shortcut as a "remote". If we're talking about a single repository (which we have to to compare against subversion), the repository is local anyway.

Git wins.  Command is unnecessary.

svn update:: Bring changes from the repository into the working copy. git fetch; git pull:: git-fetch synchronises a tracking branch with a remote repository. Git pull can be used to merge those changes into your working branch.

Git wins. The ability to track an upstream repository in a separate branch, without having to merge until you're ready is a boon. The commands "git-fetch" and "git-pull" are badly named, but the fact that they are separate functions makes it far less traumatic to regularly run "git-fetch" than "svn update".

[no svn equivalent]:: git ls-files:: Information about files in the index/working directory.

Git wins. git-ls-files can show modified files, tracked files, ignored files, deleted files, untracked files - all in a format that is easily piped to other commands.

Discussion ----------

What would git need to do to win in every section?

Subversion won:
 - svn cat: the git equivalent is too complicated.
   It wouldn't be hard to write a git-cat; if git's aliases allowed
   pipes, it could be done instantly.
 - svn checkout: the output from git-clone is unfriendly.
   -------------------
   remote: Generating pack...
   remote: Done counting 6 objects.
   remote: Deltifying 6 objects.
   remote:  100% (6/6) done
   Indexing 6 objects.
   remote: Total 6, written 6 (delta 0), reused 0 (delta 0)
    100% (6/6) done
   -------------------
   What are "objects"?  What is deltifying?  Why does object count
   matter to me?  What is indexing?  How much data was transferred?  How
   long did it take?  How big is my local clone?
   
   While transferring: how long is it going to take to finish?  How much
   data is there to transfer in total?
 - svn list: this only wins because the default output of git-ls-tree is
   so user unfriendly.
 - svn cleanup: git-fsck-objects, git-prune and git-repack all need too
   specific knowledge of git.
   
   They also need running too often on the user's initiative.  It would
   be nice, for example, if git-reset, git-rebase and git-branch could
   detect when a prune is going to be needed and give the user a hint.

   As to git-repack and git-fsck-objects - when _should_ these be run?
   How is the user meant to know?
 - svn help: subversion only won this because the help for almost every
   command fits on a page.  Git commands have so many options that need
   such a lot of explanation that it's almost impossible to think of a
   way that this problem could be solved.

Git draws with Subversion:
 - svn resolved: Subversion only knows files are conflicted because they
   are marked as such.  git has good ways of detecting conflicting files
   but has no interface around them.  It would be nice to have a
   git-resolve command that could pick "ours", "theirs" or "mine" and
   update the index accordingly.
 - svn revert: it's not easy to revert a single file in git; especially
   once we bring the index into play.  Restoring a single file in the index
   to HEAD while leaving the rest of the index AND the working directory
   untouched requires something like 
   ----------------------------------------------------
   git-ls-tree file | git-update-index --index-info
   ----------------------------------------------------
   Which isn't simple enough for a typical user.

Conclusion ----------

Git is a perfectly adequate Subversion replacement. For a user who would only want the features that they already have, they could surely get to grips with the git UI quickly.

---------------------------------

Andy

On Wed, Dec 13, 2006 at 10:00:37PM +0000, Andy Parkins wrote:

Well, you could argue whether adding something to the index is really adding it to "a repository".

Still, unfriendly, but not quite as bad:

	git -p cat-file -p revision:path

though note slightly different default. (Diffs against index, not HEAD).

From: Robin Rosenberg <robin.rosenberg@dewire.com>

Since you can give a version and a path name to git-cat-file, mention it in the man page.

Signed-off-by: Robin Rosenberg <robin.rosenberg@dewire.com>
---

 Documentation/git-cat-file.txt |    8 ++++++--
 1 files changed, 6 insertions(+), 2 deletions(-)

Robin Rosenberg wrote:

Very nice, with the exception that git cat-file can be used also for trees and commits (although hit-ls-tree and git-show are usually used) and for tags, not only for files.

I thought rather about copying last (or two last) entries about extended sha1 syntax from git-rev-parse(1).

Hi,

On Thu, 14 Dec 2006, Jakub Narebski wrote:

The point is: you are much more likely to look at a blob that at a tree. And if you want to do that, you can always use git-ls-tree.

But as I mentioned in another thread, I'd rather see git-show do the job of showing blobs, too, in addition to commits as it does already.

Ciao, Dscho

Johannes Schindelin wrote:

More important is that git-cat-file is used for _tags_; git-show used for tag takes tag as <commit-ish>, so it cannot show tag.

By the way, it would be nice to have this discussion added to GitWiki:
  http://git.or.cz/gitwiki/GitSvnComparsion

Andy Parkins wrote:

You can use extended sha1 syntax, described in git-rev-parse(1) (although
it would be nice to have relevant parts of documentation repeated in
git-cat-file(1)), namely
  git cat-file -p REV:file
(and you can use "git cat-file -p ::file" to get index/staging area
version)
 
As for alias: what about "alias.less = --paginate cat-file -p",
set using "git repo-config alias.less '--paginate cat-file -p'"?
 

git-fsck-objects is needed only if something doesn't work when
it should. "git repack" is safe, "git repack -a -d" is almost safe,
while "git prune" is not.
 

Perhaps git-archive should support "tree" format, i.e. writing
unversioned copy of a tree to filesystem.
 

There was discussion about adding thin wrapper around git-update-index
to specifically mark resolved merge conflicts. The option to pick up
ours, theirs, ancestor version is another argument for having such command.
 

There was talk about adding "git reset [<commit-ish>] -- <file>".

It can be done without pipes: "git cat-file -p REV:file". You can use aliases to have shorter name for that.

Hmmm... I thought that some progress indicator of download/upload was added... guess I was wrong.

Yes; I didn't remember that one.  However, it's still not friendly.

Yes - /I/ know that; bear in mind though that this is intended as a comparison against subversion for a user who doesn't want to know how it works. How is that sort of user meant to know when they should run each of these commands? Git doesn't tell them, it doesn't even give hints. As you say, "git-prune" is not necessarilly safe - how does a new user know that? It's in the output of "git".

I think git is pretty good in the archive department. git-archive does exactly what it says on the tin, which is exactly what you would want.

I think it's definitely a good idea. If you introduce git-update-index as a command a normal user will type, you've got a lot of explaining to do as to what else it does and why it does it.

This is the problem though. I realise that git can technically do an awful lot of these things, how many new users are going to stick around when you tell them that they have to learn about the config file and aliases before they can use the command they want?

You're not wrong, there is a progress indicator, but it's measured in "objects" not megabytes. It's got a percentage as well. Neither of these things is a whole lot of use if I want to know how much data (in megabytes) has been transferred, how much is there left to go and how long is it going to take.

Andy

Andy Parkins wrote:

No, what you see is if I understand correctly progress indicator for local and remote generating pack to send / exploding pack into loose objects (or not). There was some patch to add download/upload progress indicator, but I guess it was not applied.

Jakub Narebski <jnareb@gmail.com> wrote:

There is one that gets started when the transfer is taking a while, but it shows the total number of MiB transferred and the current transfer rate. I don't think there's a way to tell when it will be done, just that its running and running slower than you might like. :-)

Part of the problem is the remote end doesn't know how many bytes are needed for the pack its sending until after it has finished sending the pack. Sort of a catch-22.

[...]

I would appreciate this. The first thing which comes to my mind if I have to actualy revert a change I made was

	git reset file

After that didn't work I figured out I have to use the seperating -- and typed

	git reset -- file

and that didn't work, too. After several hours (ok, I'am just exaggerating, it took me only about 15 minutes) reading manpages I figured out that I have to use git checkout [<revision>] -- file

After putting some thought into the mental model behind git checkout -- file this command it looks obvious and understantable, but in _my_ mental modell

	git reset [<revision] -- file

would be a much better fit.

-Peter

Andy Parkins <andyparkins@gmail.com> wrote:

better:

  git cat-file -p $REV:$file

not sure how much easier it gets than that. Load in the bash completion from contrib/completion and you can even tab complete the $file part.

Documentation flaw that the above wasn't clear?  Or is "-file" and
"-p" the losing part for Git?
 

True, but I'm not sure its fair to Git. svn cleanup is also a technical command that one needs to learn either when something went wrong or later once the user has gotten used to using SVN. Git's fsck-objects, prune and repack aren't usually needed until the user has had a chance to use it for a while and accumulate a number of loose objects.

The last time I ran fsck-objects was when I was trying to debug that empty tree object missing in git-merge-recursive. Usually I don't see repository corruption, and even there wasn't any.

or git merge now.  :-)
 

This is one of Git's killer features over SVN. Git does merges right. SVN doesn't. Though I keep hearing its on their TODO list.

Some people like having the empty directory tracked by the VCS, as
then the build system doesn't need to create it.  I perfer keeping
all object files in a single directory which the build system
creates, as cleaning up is just "rm -rf output" (or whatever it is)
so I could care less about empty directory tracking; I think most
people are that way.
 

See above.

How is it unfriendly? What specifically would you change to make it more friendly?

You don't want to prune every time these happen.  When you start to
make use of the reflog pruning too often is a huge loss.  I actually
maybe prune my active repositories once every couple of months,
the extra garbage hanging out is usually peanuts.
 

As to the former it depends on your OS (Windows you want to pack more often) but git-count-objects gives you a good indication of how many loose objects exist. git-fsck-objects probably only needs to be run if something is not working right and you suspect an object is missing.

Shawn Pearce wrote:

Actually, tab completion allows to complete both $REV and $file part.

Jakub Narebski <jnareb@gmail.com> wrote:

Good point. Unless $REV is a SHA1 in hex format, as tab completion for commits in hex SHA1 isn't supported.

Though I have thought about implementing it.  ;-)

On Wednesday 2006 December 13 22:56, Shawn Pearce wrote:

Yes. I was a little unfair on that one; I forgot about the REV:file syntax. However, it's still not simple for a new user; I think I'd say "draw" if the "-p" weren't a requirement.

Yep. Especially when combined with the fact that the command is called git-cat-file. A new user could be forgiven for thinking that meant that they could cat one of their files held by git. Also: they have to read a man page to find out that they need an option and which option is correct. I reckon git-cat-object would be a better name ("no chance!", I hear you cry ;-))

I've just noticed as well that the documentation is wrong:
 $ git-cat-file HEAD:Makefile
 usage: git-cat-file [-t|-s|-e|-p|<type>] <sha1>
The square brackets indicate "optional", and those items clearly aren't.  I'll 
fix the documentation.

My point is that a user can run "svn cleanup" without thinking, or needing to really know what it does. Not so for git's maintenance commands. Also, there are more commands. I'm not saying they're not useful or necessary, but it's certainly more complicated than subversion.

For example: I used subversion for a long time - I don't think I ever had cause to run "cleanup", I'm not even really sure what it does. I /have/ had cause to learn what git's maintenance commands do; which in turn meant I had to learn how the git repository works. (I personally don't mind learning those things, but it's wrong to expect every user to do so).

Me too. I've never run it in fact; but the command exists and therefore needs learning.

Hurrah! However, at the time I wrote the comparison (and with 1.4.4.1.g3ece-dirty I've got here) git-merge is still the old, more complicated, command line.

Absolutely. Although, even if SVN does implement it, it's going to be a hack. It'll just be an extra svn:special property set somewhere in the repository, or similar. I can't see how they can do merges properly with the methodology that SVN uses.

You're right; as it happens I'd prefer it if git could store empty directories. However, in terms of "what I have to learn", git definitely wins this category because there is nothing to learn - make whatever directories you like; it will generally sort itself out.

$ git-ls-tree v1.0.0 100644 blob 906e98492080d2fde9467a9970fc92d7a8cfeaf8 Makefile

I'm a newbie: what's that number at the front? What's a blob? What's that great big number - I've only seen commit hashes that look like that, and that isn't one. Definitely not friendly.

$ svn list -r 14 Makefile

It could probably be fixed by making git-ls-files capable of understanding tree-ish.

You are correct of course. They don't need running regularly, and in a way that makes it worse. How is a user who isn't familiar with git internals meant to know they should run git-prune? How are they meant to know when they should run it? How are they meant to know that it is git-reset, et al, that create conditions that need them to run git-prune?

Personally I like my repository pruned fairly often. This makes it much easier to find the commit I need to restore when I've accidentally done a git-reset I didn't mean to. If I had to search through three months worth of dead objects it would take me all day. However, I don't think that affects a new user at all. Recovery from disasters should be expected to be hard.

Yep, /I/ know.  How is my imaginary new user meant to know?

My rhetorical questions are the key to making git friendly I think. Each one represents a hole - it's not that there is no answer, it's that there shouldn't be a question. The hard part (as always I suppose) is that we have to imagine a new user; this makes all my babblings above highly subjective. As such I won't be that upset if I'm told to "blow it out my ear". Whatever that means.

Andy

Andy Parkins <andyparkins@gmail.com> writes:

I would say pretending as if cat-file is a Porcelain is the unfair part.

Again, mistaking ls-tree as if it was a Porcelain is the true cause of the newbie confusion.

I think that's a wrong way to go about. The primary purpose of ls-files is to read the index and show information around it; ls-tree is about reading one tree and show information around it. They are both plumbing and meant to be used by scripts when they want to inspect the index or a tree respectively.

If a Porcelain level "ls" is needed (and I am doubtful about usefulness of "svn list -r538" like command), that is the command you would want to teach about using ls-files and ls-tree depending on what the end users want in their workflow.

On Thursday 2006 December 14 09:44, Junio C Hamano wrote:

I had to; there is no other equivalent of "svn cat" in git.

Again, there is no other equivalent of "svn list" in git.

Me too. I was in no way advocating that git should try to be SVN (shudder). As I was comparing though, I had to pick git commands that did at least what SVN could do.

Personally, I think qgit fills an awfully big hole in svn that makes them all irrelevant. qgit is a much better repository browsing tool than "svn list" is.

Andy

On 12/14/06, Junio C Hamano <junkio@cox.net> wrote:

+1. Any chance git-ls can go to 1.5.0?

Hi,

On Thu, 14 Dec 2006, Nguyen Thai Ngoc Duy wrote:

Two questions arise naturally:

- what do you need it for?

- have you seen the patch for git-show today, which would include this 
functionality?

Ciao, Dscho

Hi,

On 12/14/06, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

for being user-friendly and consistent. Git porcelain commands seem to be grouped by function. So it would be natural to have git-ls as a front-end for both ls-files and ls-tree. I don't really care about ls-tree but I do about ls-files to examine index.

I didn't. From the patch, it seems git-show can show the index via ::file syntax. If so, I'd like withdraw my opinion. '::file' syntax is not intuitive though. Perhaps you should mention that it can show index (and how) in the git-show document

Hi,

On Thu, 14 Dec 2006, Nguyen Thai Ngoc Duy wrote:

Okay, I only thought you had a use case, which could have been possibly better served by other commands.

Well, you can reference blobs that way, but not trees.

Ciao, Dscho

Hi,

On 12/14/06, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

Oh, yeah. Isn't this a good oppotunity to add --index option to git-show? git-show --index will show the index. git-show --index file will show the file content. This makes git-show a little unconsistent though as it may or may not require argument <object>.

Another option is treat '::' alone specially -- call git-ls-files.

Hi,

On Fri, 15 Dec 2006, Nguyen Thai Ngoc Duy wrote:

Hmm. I don't know... It would make the code rather messy. And are you really interested in the content stored in the index? In all cases I can think of, you are better off with a diff vs. working directory or ref.

Ciao, Dscho

Hi,

On 12/15/06, Johannes Schindelin <Johannes.Schindelin@gmx.de> wrote:

When I worked with index the first time, I had difficulty knowing what was in index. Index is, unlike working directory, intangible. I could use git-diff (and actually did), but it was still better if I could have seen what exactly was in index.

To me, index and object database are (to some extent) the same: both are used to store files. If I can examine git object database, why not index?

About adding index support to git-show, yes it's really messy. index doesn't have tree objects. If a user wants to list a subdirectory in index, git-show will have to do more work, I think. Perhaps we should forget this for now.

Hi,

On Fri, 15 Dec 2006, Nguyen Thai Ngoc Duy wrote:

Insofar, it is not messy: git-show only shows _objects_. For example, "git show :README" works as expected if you have a file called "README" in the index...

Ciao, Dscho

Hi,

On Fri, 15 Dec 2006, Johannes Schindelin wrote:

Note: this is not completely true. The index contains cache_trees. But 
they do not need to be up-to-date, which would mean that "git show :./" 
would have to remake the cache_tree, and _then_ show it.

Ciao, Dscho

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:

Let's not go there.

I was reviewing the list of plumbing in Documentation/git.txt last night, and I think ls-files is the only command that user may still want to use from the command line every day.

I originally thought that it would only be after a conflicted merge, always with -u option, but some people seem to find that "ls-files --others" and friends are useful (I never use that myself) and if so what it does really in the realm of Porcelain.

I haven't formed a firm opinion on this yet, but possibilities are:

 * we reclassify ls-files as a Porcelain-ish (but do not change
   its UI nor defaults at all); we might want to give a shorter
   alias to the command, though, if we go this route.

 * we give '--list' option to 'git show' and in such a case,
   lack of objects does not default to HEAD -- when no object is
   given it internally diverts to cmd_ls_files() instead;

 * we add 'git ls' command to give Porcelain-ish access to
   ls-tree and ls-files.

On Fri, 15 Dec 2006, Junio C Hamano wrote:

That seems the most sensible to me.

On 12/16/06, Nicolas Pitre <nico@cam.org> wrote:

I agree.

Andy Parkins wrote:

  $ git repo-config alias.less "-p cat-file -p"
  $ git repo-config alias.cat     "cat-file -p"

remedies that.

[...]

The number in front is octal mode of a file or directory. "blob" is a file (or symbolic link), "tree" is a directory, all of this can be found in git(7).

The "great big number" is blob hash. All objects are identified and referenced by SHA-1 hash of its contents: be it commits, blobs (contents of a file), trees (content of a directory), tags.

You can always use --abbrev option to have it shortened.

Perhaps we should add git-ls which would be porcelain frontend to git-ls-files and git-ls-tree, just like git-diff is frontend to git-diff-files, git-diff-index and git-diff-tree (and also does pure blob diff).

"svn list -r 14" equivalent is "git ls-tree --name-only v1.0.0". You can always do

  $ git repo-config alias.list "ls-tree --name-only"

(or use --name-status instead of --name-only).

On Friday 2006 December 15 11:27, Jakub Narebski wrote:

Sorry, when I said "I'm a newbie", I meant "pretend I'm a newbie" :-)

My point was that this is all too confusing for a newbie; the fact that you had to descend to talk about SHA-1 and blob hashes, really serves to strengthen my point. What does a non-developer care about hashes, blobs, trees, commits, or objects?

In this case however, I withdrew my complaint because it's argued that git-ls-files is not the right tool for this purpose anyway.

Andy

Shawn Pearce <spearce@spearce.org> writes:

FWIW, after some amount of git experience, I had a need for git cat-file and I found it hard to use. Why? Because following the pattern of some other commands, I really expected the following to work:

   git cat-file -p HEAD^2 $file

Since that is similar to

   git diff HEAD^^ $file
   git checkout HEAD $file
   
Where else uses the colon syntax?

My $0.02.

Seth Falcon wrote:

You mean

    git diff HEAD^^ -- $file
    git checkout HEAD -- $file

It's not $file, it is $path, and it is limiter. git-cat-file (the name
is certainly historical artefact and it should be git-cat-object) doesn't
support limiters.
    

Everything where you have <object> or <tree-ish> you can use colon syntax. For example:

  $ git ls-tree pu:Documentation
  $ git grep -e --merge next:Documentation
  $ git diff v1.4.2:gitweb/gitweb.cgi gitweb/web:gitweb/gitweb.perl

onsdag 13 december 2006 23:00 skrev Andy Parkins: [...]

I'd say svn clone is the nearest equivalent as it does the initial fetch of data, no checkout is necessary after clone. it checks out master. Then you git-checkout to switch branch, which corresponds to svn switch.

You'll need to push too in order to get a copy in a central repository. git-commit stays locally, and you need a place to push to. If your SVN repo isn't local this does not apply. git gives more freedom here.

svn copy is more like git checout -b, i.e. it's primary purpose is not to "copy" things, it is to create branches. You generally do not copy code (I hope).

In svn this also renames a branch.

svn switch corresponds to git-checkout. I don't think you can change the URL unless the new URL actually points to the same repository.

[...]

Typically the user want to restore the index AND the working directory. Comparing typical workflows is more interesting than finding exact equivalents.

Andy Parkins <andyparkins@gmail.com> writes:

ls-tree is not Porcelain and has right to expose the internals by default. "git ls-tree --name-only" could be aliased to give "git ls" if you wanted to, but I wonder how often you would want to run:

	svn list -r538

and for what purpose?

I often find myself doing

	git diff -r --name-status v1.3.0 HEAD

to check if a file was already in v1.3.0 version, and I could do the same thing with

	git list v1.3.0 >/var/tmp/1
        git list HEAD >/var/tmp/2
        diff -u /var/tmp/[12]

but that certainly is awkward.

What do people use "svn list -r538" for and how often? In other words, when does it become necessary to get the full list of paths in an arbitrary revision?

On Wednesday 2006 December 13 23:45, Junio C Hamano wrote:

Of course; but there is no porcelain to do that operation.

I've never done it. However, the command is there in subversion, so I was comparing git's implementation of that command. I wouldn't completely write it off though. It doesn't seem unreasonable to want to see what files were in an old revision.

I can live with that as an acceptable alternative to "svn list"; however, as usual, how does my imaginary ex-svn user find out about that? man git-diff isn't the first place /I'd/ go; and even if you do, you won't find the "-r" or "--name-status" options; you have to go to git-diff-files, git-diff-index or git-diff-tree - and you're meant to guess which is the right one.

Bear in mind that my current theme isn't "can git do...?" it's "how does a user know that git can do...?"

Me: I don't do it often.  It's not something I'd lose sleep over if git 
doesn't have an easy way of doing it.  However, it was in the output 
of "svn --help"; so I included it.

Andy

On Wednesday 13 December 2006 23:00, Andy Parkins wrote:

subversion is a winner when it comes to options handling (especially --help) and better (error) messages. That's one of reason why people find it easy.

ps. I'm blind or there is no documentation about what utilities are needed to get git fully working? (like sed, coreutils, grep, rcs package (merge tool afaik needed)...).

Arkadiusz Miskiewicz wrote:

Yup. Most discussions about what git can do to improve usually ends up in a patch that fixes either documentation or error- / help-messages.

perl and the standard coreutils, which afaik are required to be present on all unix systems. We no longer require external merge tools.

On Thursday 14 December 2006 23:07, Andreas Ericsson wrote:

That's not all. sed and grep is also used. There may be some others hidden deep in git and it would be good to have that docummented (I've hit the problem already with missing some tool when preparing chroot for git).

Starting from which version?

Arkadiusz Miskiewicz <arekm@maven.pl> wrote:

Not released yet, its sitting in 'next'.  Hopefully 1.5.

Arkadiusz Miskiewicz wrote:

sed and grep are, along with awk, part of the tools that are required to be present on all unix systems. Sorry for the confusion with coreutils (the package / software project).

When you set up a chroot environment, you want to at least copy /bin, /lib and /sbin to the new root and then remove whatever you *know* you don't need from them. Those directories should hold all programs the system needs to properly boot up.

Latest only. It was added 2006-12-06 and the dependency on external merge program was removed in a commit created 2006-12-13. Junio merged the merge-code into master one hour later. It is not in the maint branch, so I don't know if any distributions ship git with the new xdl_merge() thing. It's *very* good though. Kudos to Johannes Schindelin for really making things right.

Hi,

On Thu, 14 Dec 2006, Arkadiusz Miskiewicz wrote:

Open the file "INSTALL".

Hth, Dscho

Johannes Schindelin wrote:

Which doesn't mention 'sed' for example. 

I have checked only commands in POSIX shell script; this list does not include tests in t/ directory, which uses multitude of other tools.

Git has built-in grep since at least v1.4.0, but 'grep' is used in generate-cmdlist.sh, git-commit.sh, git-instaweb.sh, git-quiltimport.sh and git-tag.sh.

'cut' is used only in git-instaweb.sh; other commands do without it. 'sort' is used in check-builtins.sh, generate-cmdlist.sh, git-ls-remote.sh, git-tag.sh. Both tools are from coreutils package. And git uses other tools from coreutils too: uniq, printf, tail,...

Git has built-in diff since at least v1.4.0, but diff is used in git-merge-one-file.sh