Giteveryday – A useful minimum set of commands for Everyday Git

https://www.kernel.org/pub/software/scm/git/docs/giteveryday.html

by ymse • 10 years ago

114 52 10 years ago

libeclipse• 10 years ago

Wow, a man page that is actually readable and understandable.

I've been using Linux for years, and never once have I seriously looked at a man page. One of the more useless pieces of advice Linux beginners are given is to `man [tool]`. The documentation often has tonnes of useless information and no examples. It's frustrating, and it's also why projects like tldr[0] have gotten so popular.

But, the page linked in the OP is actually brilliant. It's easy to read, has examples, compartmentalises into sections that are relevant to different people. It's a step in the right direction.

Note: I'm not saying there aren't other pages like OP. There probably are, but the vast majority are not.

[0] https://github.com/tldr-pages/tldr

ekr• 10 years ago

One place where the MSDN docs is way ahead of the manpages is the documentation of function paramters. For instance, here's the ouput of man 2 write.

  ssize_t write(int fd, const void *buf, size_t count);

  DESCRIPTION
  write()  writes  up  to  count  bytes  from  the buffer pointed buf to the file referred to by the file descriptor fd.

  The number of bytes written may be less than count if, for example, there is insufficient space on  the underlying  physical  medium,  or the RLIMIT_FSIZE resource limit is encountered (see setrlimit(2)), or call was interrupted by a signal handler after having written less than  count  bytes.   (See  also (7).)

  For  a  seekable file (i.e., one to which lseek(2) may be applied, for example, a regular file) writing takes place at the file offset, and the file offset is incremented by  the  number  of  bytes  actually written. If the file was open(2)ed with O_APPEND, the file offset is first set to the end of the file before writing.  The adjustment of the file offset and the write operation are performed as  an  atomic step.

I have to go through a block of text scanning for the parameter I'm interested in. When I'm using the manpage as a reference (which is most of the time), this is less than ideal.

MSDN indexes the documentation by parameter so you can quickly find what you're interested in.

LE. Sample msdn link for comparison: https://msdn.microsoft.com/en-us/library/windows/desktop/aa3... .

qwertyuiop9242• 10 years ago

That's actually just one sentence you have to scan, so I don't totally see the issue.

brohee2• 10 years ago

That's under Linux (not sure if that man page is maintained by glibc or the kernel seeing as it is a syscall).

That's pretty different under a system that cares : http://man.openbsd.org/OpenBSD-current/man2/write.2

koytch• 10 years ago

Sections 2 and 3 contain the most readable man pages out there. The pages in sections 1 and 8 are often terrible, being the result of some texinfo->man filter.

pjc503• 10 years ago

One of the things that never ceases to amaze me is how slow MSDN is. It feels faster to look something up on stackoverflow, even if it's not as well organised.

Version-specificness on MSDN is often a little odd. I do Windows CE and for some reason Google returns hits from the Wince5 docs more often than the rest, and it's not straightforward to get to the docs for a different version. Sometimes this is important.

qwertyuiop9242• 10 years ago

man pages are quite useful as reference documents. Which is their intended purpose.

tmsbrg2• 10 years ago

I have the idea of creating a tool which is more like a tutorial for commands rather than the reference that `man` is. Has anyone made something like that before?

I thought of giving it a name like `tutor`. Where you can use it without arguments for a general shell tutorial and with arguments for a mini-tutorial about a command

$ tutor

Welcome to the Bash command shell. This is a short tutorial about how (and why) to use the shell...

$ tutor ls

Use `ls` to view files in the current directory or one you specify. Examples:

- ls

Lists current directory (excluding files starting with a ., these are "hidden files")

- ls -A

Lists current directory including hidden files ... ===

Something like that at least. I think one of the worst things about the shell is finding out about the functionality there actually is, so having something like that built in could be handy. Maybe you could also have it do something like `tutor copy file` and have it find and list commands that fit the description.

andrewchambers• 10 years ago

Try a project like freebsd or openbsd for better man pages that are centrally curated.

jlgaddis2• 10 years ago

One of the more useless pieces of advice Linux beginners are given is to `man [tool]`.

On the other hand, when I was first introduced to Linux ~20 years ago, I didn't have an "always-on" Internet connection and web sites weren't that popular.

Probably 90% of what I learned in the first few years or so came from the man pages and a locally downloaded copy of the guides and howto's from TLDP [0].

I might also mention that not all man pages are created equal. I've seen some in Ubuntu that serve no purpose other than wasting bytes on the disk while some of those in OpenBSD act as a single source for everything one needs to know about <tool>.

[0] http://www.tldp.org/

jasoncchild• 10 years ago

Same here; I was constrained to what was on my stack of floppies comprising my Slackware dist

Anthony-G• 10 years ago

Similar situation for me. My first Linux distribution was Red Hat 5.2 which included an off-line copy of the Linux Documentation Project on the CD (as did other contemporary distros such as Mandrake). Since I only had a slow dial-up connection, I found these off-line copies to be an invaluable resource. I remember using Lynx to read Guides and Howtos during the two weeks it took me to get X working on my old laptop.

After those early days, I hadn’t looked at the LDP site in ages but about 4/5 years ago I looked at the project again with a view towards contributing (now that I know more about GNU/Linux and Unix in general). However, it looks like the project was (is) largely moribund and I got the impression that the active community had dwindled significantly over the past 15 years or so – which is a pity.

hk__2• 10 years ago

I’ve been using Linux for years too, and I learned more useful things about Bash with `man bash` than anything I could find on the web.

pjc503• 10 years ago

For a while I had a printout of the bash manpage, neatly bound. It's something like 60 pages. Nroff actually produces great print output, which hardly anyone ever uses it for these days.

thms0• 10 years ago

One of the more useless pieces of advice Linux beginners are given is to `man [tool]`.

You're such an idiot, my god. Maybe get yourself a brain and you'll understand all manpages :)

djhworld• 10 years ago

Thanks for that link to the TLDR project, looks kinda interesting.

The fact that project exists though suggests to me there is a problem with the man page system in general.

pwdisswordfish2• 10 years ago

Wow, a man page that is actually readable and understandable... just like any other man page.

I've been using Linux for years, and never once have I seriously looked at replacements for man pages. In your average man page, I can look up even the most obscure option and know exactly how to use it and what it actually does. With a detailed enough man page, I don't even need to look anywhere else much of the time. It irritates me when I have to lookup documentation which isn't written in a similar format. (Say, LaTeX.)

I don't see any appeal in "tldr pages" or "bro pages", and frankly, I get rather annoyed when every once in a while I see HN posts promoting projects like that which basically reinvent the square wheel instead of solving the real problems of man pages (which I'd say there are two: lack of hyperlinks and poor searchability).

cx10002• 10 years ago

I have never heard of bro pages before. It sounded like a pejorative but it's actually a thing http://bropages.org/. I find them to be a lot of wasted time too and totally agree about the hyperlinks. As far as searching man pages, I do pretty well with the trusty forward slash. Would you prefer more semantic searching like google?

catern3• 10 years ago

solving the real problems of man pages (which I'd say there are two: lack of hyperlinks and poor searchability

texinfo (info) has hyperlinks, and I can search through multiple manuals if that's what you mean by searchability. And it's probably already installed on your system.

JdeBP3• 10 years ago

lack of hyperlinks and poor searchability

Meet Daniel J. Bernstein's slashdoc.

* http://cr.yp.to/slashdoc.html

whack2• 10 years ago

I've generally found that most man pages are primarily useful for people who already know the basics of how to use that tool, and need to consult the man page in order to figure out how to understand/accomplish some specific functionality they're looking for.

On the other hand, if you're completely new to the tool, man pages are pretty much useless like you mentioned. I generally just google for "<tool> tutorial" instead.

JdeBP3• 10 years ago

It's worth noting that there's a difference between reference documentation and tutorials. The world needs both, of course. The user manual on Unices and Linux operating systems is meant to be reference doco.

In the BSD world, in addition to the user manuals there are the various handbooks and guides:

* https://freebsd.org/doc/handbook/

* https://netbsd.org/docs/guide/en/

* https://www.trueos.org/handbook/trueos.html

* http://dragonflybsd.org/docs/handbook/

The Linux world has the Linux Documentation Project, but that is of variable quality, has patchy coverage, and is wildly outdated in some areas.

There's a collaborative project on Wikibooks, as well.

* https://en.wikibooks.org/wiki/Guide_to_Unix

paulddraper• 10 years ago

For beginners, sure. Point them to tutorials or heavily abbreviated documentation.

But I want to list all commits in the topological order they are in the graph, or need to understand date format specifiers, man git-log .

I actually think quite highly of git's man pages for anything more than rudimentary first steps.

erikb3• 10 years ago

I love that they try to make it assessible. But I disagree with that it would be an acceptable goal in git just to understand a subset of it. You need to understand nearly everything, even the internals. Only then it can really become useful to you.

The mistake the community made is putting git on the throne of version control. It's not. It's a tool for experts that can do a lot for you if you know how to use it. But to achieve that it pays the price of not really being assessible.

Now that it's in its position, the best thing you can do is to learn it. There is the git book. Read it. Annoying, I know. But that's the gameplan. Not doing it is just dragging out the inevitable.

logicallee• 10 years ago

This is a very useful comment.

I think the same could be said about C. It should not be put on the throne of "programming language" - you need to actually read and understand what it does internally. (pointers etc) - it's not enough to learn some incantations.

So then let me ask: is there a room for x, where git:x::C:python (git is to x, as C is to Python).

People everywhere deserve to have x. Not just right-clicking a file in Dropbox or OS X for previous versions, but a full commandline and detailed history including commit messages, and many other aspects of git.

In a way this is completely orthogonal to your comment, just as Python is to C.

EDIT: I've thought more about it and I no longer agree. The "language" presented here is a subset of C/C++ - not everything is mentioned or taught: https://www.arduino.cc/en/Reference/HomePage

It is in fact exactly this type of simplified subset. Not even malloc and free are mentioned... So while what you wrote is true for this audience (HN) there is room to learn less or a subset.

nothrabannosir• 10 years ago

Mercurial. I'm not being flippant; the UX is light years ahead in terms of accessibility to newcomers to dvcs. With a ui like tortoisehg, even five years ago, someone without any prior experience in any vcs at all could become productive after a fifteen minute primer. Git does not compare.

erikb3• 10 years ago

Yes, I believe as well there should be an assessible solution and that should be the standard. However in this case there is none, since weirdly enough git is sitting on the throne. You can try to establish other tools like mercurial in some projects, but you may end up getting harsh resistance by exactly the people you try to serve with that option.

trolor• 10 years ago

Potentially dumb question here, but couldn't 'dragging out the inevitable' be another way of phrasing 'the learning process'? It seems that immediately making a tool usable would be preferable to keeping it as a purely theoretical device until it's fully learned.

erikb3• 10 years ago

If you are this kind of person who is interested to learn, but has no problem with using stuff despite it being a little rough in the beginning, then yes you are more than welcome. In fact I would say that is how people learn. You cannot just read a book. You also need to use it.

But that is not how most beginners approach tools. For most people a tool should serve a purpose and do that immediately from the get go. And for them git is really painful in the beginning. And if they don't put in the learning effort it will still be that annoying a few years down the road.

That's what I meant. Thanks for letting us clarify that together.

whack2• 10 years ago

"But I disagree with that it would be an acceptable goal in git just to understand a subset of it. You need to understand nearly everything, even the internals. Only then it can really become useful to you."

Sorry, but this is patently false. I've been using git very effectively for years, both as a participant and as a repo admin, have had other Senior Developers call me a "git hacker" and ask me for git help, and I have no idea how the internals of git work. I also use a very small subset of git functionality, and many of the commands in the OP look like greek to me.

I don't doubt that your approach is one way to learn/use git. But learning git as a black box, and using just the parts you need, is perfectly useful as well.

guard-of-terra3• 10 years ago

Both merge and rebase, but no cherry-pick. Goodbye then, I guess.

I've seen a dozen of those tools wishing to "simplify" git and they all fail my workflow, which is pretty common I guess, team git with central server and source control.

What I use:

    git push with target

    git fetch

    git checkout

    git cherry-pick

    git reflog

    git log, status, diff obviously.

pjc503• 10 years ago

Why git cherry-pick rather than just fast-forward or rebase? Doesn't that introduce a whole bunch of duplicate commits?

guard-of-terra3• 10 years ago

I don't care about any commits that are not under code review. If I have fifty duplicate commits on different branches in my local, that's okay with me.

Fast-forward doesn't work usually, and rebase is confusing compared to cherry-pick.

dagss• 10 years ago

The difference between rebase and cherry pick is very very slim, rebase is in a sense just a convenience frontend for cherry-pick..

guard-of-terra3• 10 years ago

For rebase I can never figure out what should go in all its parameters. It has defaults sure, that are impossible to figure out either.

With cherry-pick you have no parameters and no defaults, it's basically cp <commit> . for SCM.

captn3m0• 10 years ago

This is my favorite documentation link I give to others when teaching git.

JdeBP3• 10 years ago

Have you considered helping to complete https://en.wikibooks.org/wiki/Git ?

user5994461• 10 years ago

Useful commands for everyday GitHub usage:

# apt-get remove git

# apt-get install svn

Then use svn. You can receive and send code to GitHub. GitHub is fully svn compatible =)

That can be especially handy for non-tech folks who would have an impossible time with git.

Giteveryday – A useful minimum set of commands for Everyday Git

Related Stories