"git revert" would have been clearer if it were identical but just named "git retract". It's a more natural match because reverting usually just means going back to how things were, whereas retracting can and often does mean to announce that you are going back. After a newspaper prints something untrue or unfounded, they issue a retraction.
"git checkout -b" is confusing because the main and most significant thing it does is create a new branch, and checking it out is secondary to that. If it had been "git branch -c" instead (create a branch also check it out) that would have been more natural than "git checkout -b" (check out a branch that, incidentally, you will have created).
"git reset", as you mentioned, does two things. This could have been made easier by just splitting it into two commands. Perhaps the first two forms could be called "git unstage". The git book ( https://git-scm.com/book/id/v2/Git-Basics-Undoing-Things ) explains it under a heading called "Unstaging a Staged File", which suggests that it's a more natural term.
"git remove" should then be "git delete".
> Naturally, people get confused and reach for the docs, which are filled with even more newbie-hostile terms like 'tree-ish', 'hunks' and 'refspec'.
Yup, these are everyday terms for an expert in computer science and algorithm and software design. If I were a student in medical school I'd expect the books I'm learning from to use the expert terminology of my domain of study when describing the body and functions and not laymans terms such as -- "the hip bone is connected to the Red-Squishy-Thing .... ELI5 me plz" ...
I agree git is complex, and can be scary. But building software is a complicated process rife with engineering pitfalls! If one is unable to properly use the Lego building blocks, then stay away :D
I do believe when used properly, a productive Git workflow using Branches and sane commit messages can help to give Visibility to your project development life-cycle and help to make an issue or task on a project understandable in scope and difficulty by segmenting ones development work into comprehensible mergable pieces (branches) within the project.
Git is not friendly period, it's a huge pile of leaky abstraction and incoherent commands, the "high-level UI" being closer to shortcuts for common sequences of lower-level operations than an actual abstraction. It simply can not be understood "top-down".
> It's original intended audience was not lay people learning how to program. It was seasoned kernel developers working on the Linux source tree. It (made) assumption(s) it's userbase were experts in their domain.
Domain expertise has nothing to do with it, unless the domain is playing with footguns and expertise is having toes left.
> I agree git is complex
Git is not complex, it just has a very, very shitty API.
people with any kind of technical knowledge of a domain tend
to get hopelessly (and unwittingly) stuck in a frame of
reference that relates to their view of the issue, and
their trade's technical parlance, not that of the ordinary
humans with whom they so signally fail to engage.https://blogs.msdn.microsoft.com/oldnewthing/20110512-00/?p=...
I know a few "nerds" like that. They tend to give technically completely correct but misleading or dangerous or simply unusable answers.
We don't expect journal papers to be written at an elementary level. But people who make an effort to get themselves up to speed in the area can understand them. The same thing applies to a lot of tools that are used in software development.
Git's man pages are not journal papers.
> For the most part, one has to have a basic understanding of the field
"Basic understanding of the field" does nothing for understanding Git.
> and read through prior research to have a better understanding of the current problem domain.
You should not have to "read through prior research" to be able to use a basic VCS tool, literally no other VCS asks that of you, not even Darcs (especially not Darcs, which actually put real effort into a sensible CLI).
> We don't expect journal papers to be written at an elementary level.
We don't expect tooling documentation to require a phd unless the tool's entire purpose is something only a phd would need.
> The same thing applies to a lot of tools that are used in software development.
No. It applies to very few tools that are used in software development. And git most definitely is not one of them.
Assuming one has at least read up on data structures, then one would have read about graph structures and have heard about what a directed acyclic graph is.
> You should not have to "read through prior research" to be able to use a basic VCS tool
You should have some understanding of what source control is and have read at least some of the documentation of the VCS tool you are using. I've never used hg and wouldn't know where to start without reading some of the documentation first. But having prior knowledge of VCSs and distributed VCSs would allow me to target my search for documentation about how to commit changes, how to publish them to a remote repository, how to make a branch, etc.
> We don't expect tooling documentation to require a phd
Many of these papers can be read and understood by students who are pursuing their undergraduate degree. But they do need to put some effort into it.
> No. It applies to very few tools that are used in software development.
Can I use grep without a basic understanding of how regular expressions work? Could I use a debugger like gdb without understanding concepts like the call stack and variable addressing? You have to be able to read through documentation to effectively use a lot of tools in software development.
Knowing what a DAG is doesn't help using git and Git being singularly problematic despite every DVCS being a dag indicates that DAGs have nothing to do with Git's issues.
> You should have some understanding of what source control is and have read at least some of the documentation of the VCS tool you are using.
Basic understanding of source control and the ability to read correctly-written documentation (which Git's is not) is not "read[ing] through prior research".
> Many of these papers can be read and understood by students who are pursuing their undergraduate degree. But they do need to put some effort into it.
Completely missing the point.
> Can I use grep without a basic understanding of how regular expressions work? Could I use a debugger like gdb without understanding concepts like the call stack and variable addressing? You have to be able to read through documentation to effectively use a lot of tools in software development.
Your original assertion was not the ability to read some documentation (under the assumption that the documentation actually makes sense, which isn't the case for git).
If you're not going to make even cursory attempts at basic honesty and coherence, there's no point to a discussion, enjoy playing with yourself.
How does git's documentation fundamentally differ from tools like ffmpeg or grep? That is, what makes it incorrect? I've read through those man pages and have been able to figure out how to use the CLIs for those commands.
>> We don't expect tooling documentation to require a phd
[ ... ]
> Completely missing the point.
Using hyperbole doesn't help you make a point.
> enjoy playing with yourself.
You don't have to resort to using insults.
“refspec” and “tree-ish” are obscure and git-specific.
Also Git is now more or less locked in to terrible naming for its actions - yes they could be renamed but that would probably cause more issues than its worth. And Mercurial isn't dead yet - Facebook uses it and they're rewriting it in Rust (yeah yeah) to make it faster. I don't think the VCS wars are over yet.
https://confluence.atlassian.com/confeval/development-tools-...
Here's hg help rm:
remove the specified files on the next commit
Schedule the indicated files for removal from the current branch.
This command schedules the files to be removed at the next commit. To undo
a remove before that, see 'hg revert'. To undo added files, see 'hg
forget'.
This only removes files from the current branch, not from the entire
project history, and it does not delete them from the working directory.
Remove files from the index, or from the working tree and the index.
git rm will not remove a file from just your working directory. (There
is no option to remove a file only from the working tree and yet keep
it in the index; use /bin/rm if you want to do that.) The files being
removed have to be identical to the tip of the branch, and no updates
to their contents can be staged in the index, though that default
behavior can be overridden with the -f option. When --cached is given,
the staged content has to match either the tip of the branch or the
file on disk, allowing the file to be removed from just the index.
Sure, some problems with git may be that people have trouble understanding the concepts. But many of them are due to git's impenetrable documentation and a few of the commands that do too many things. The sheer resistance of many adherents of git to recognize that it has a UX problem is just mind-boggling.
The problem with many documentations is that they are not use-case driven. Much of it is a functionality description. Such as:
- To fasten, you have to turn the nut clockwise.
instead of:
- To fit these two parts together you need to fasten the nuts onto the screws.
All of its functionality is simple variants on that. `-b` is the only real odd man out, and it’s just a shortcut for calling `git branch $branchname` first.
A few examples:
- `git reset` command can perform wildly different actions depending on its options
- `git revert` does not do what most users would hope it does
- if you actually need to revert your working tree changes, you might need to use `git checkout`
Naturally, people get confused and reach for the docs, which are filled with even more newbie-hostile terms like 'tree-ish', 'hunks' and 'refspec'.
As a result, people tend to see Git as this scary, incomprehensible hairball.