some feedback

[yihui]

sorry I do not have time to write a formal pull request (some points are not for pull requests, either), but just some feedback and comments for now:

• GIT: always use a GIT GUI; almost never git add *; I use Ubuntu, so apt-get install git-gui first, and git gui is how I work every day; I use the GUI to select minimal sets of lines of changes to commit instead of just committing everything; then
  • explain in each commit what you did, and sometimes explain why it must be done
  • if a commit fixes a Github issue, write fixed #n and Github will close that issue automatically when you push
  • if you fixed a bug, write a test accordingly, so eventually for all bugs and fixes, you know the full history, e.g. kable with one-row matrix discards row name yihui/knitr#636
• the only GIT commands that I use are git clone (once), git rebase -i (occasionally), git pull --rebase, and sometimes git checkout -b (only in case of collaboration); for the rest of jobs like git commit and git push, etc, I always use the GUI
• I find Authors@R very useful for several reasons
  • it generates Author and Maintainer automatically when you R CMD build
  • consequently, citation(pkg, auto=TRUE) generates a clean BibTeX entry; if everyone uses this, I would not have to do this ugly hack: https://github.com/yihui/knitr/blob/master/R/citation.R
• some software communities hates GPL and prefers more permissive licenses like MIT; I think they have a point (in the academic environment, GPL is often not an issue, but in the industry, GPL can be too restrictive)
• we (RStudio) have been looking into the possibility of making "reproducible" shiny apps, e.g., you can provide a list of input values or save the current state in a "bookmark", and the app can reproduce itself later

[alyssafrazee]

Hi Yihui,

I think a set of "git best practices" is probably a topic big enough for its own document :) The git and GitHub steps we listed here were pretty narrow: they basically just describe how to get one project pushed to GitHub. I agree with the majority of your git feedback, but I did want to respond to two things:

(1) you're right that git add * is not great practice in general; using it at all means you should probably be doing git status very frequently and have a good .gitignore file going. However, I don't think it's a terrible thing to do when you're first getting your repo started and want to add all your code at once, which is the context we recommended it in here.

(2) I disagree with the advice to always use a git GUI - I'd say that's more a matter of personal preference, and in fact, most developers I know do not use a GUI at all. For selecting minimal sets of lines of code to commit, git has a patch mode: you can just do git add -p and select from there the lines you want in your next commit. (here is a nice blog post on patch mode, with examples). Between patch mode, git status, git diff, and git log, most of the important visual stuff is readily available on the command line, so I think a GUI is not so much a necessity as it is a convenience.

Also...fixed #n: super awesome!

[yihui]

@alyssafrazee thanks for the reply. You certainly have your point. Conditional on your background, I agree with you :) (That is always how statisticians explain models)

I die a little bit inside whenever I see a .DS_Store pushed to a GIT repo, e.g. https://github.com/jtleek/dataanalysis/blob/master/.DS_Store With a GUI, you clearly see what you are doing. Of course, git status does the job as well; I am just highly dependent on "visualization". I love the command line interface as well as some excellent GUI's (Word or Excel is certainly not on the list). I cannot remember too many commands, so I use GUI's to assist me. Right-click and commit a subset of changes works great for me:

Other features like the visualization of the branch/commit history in git gui is also very cool. You are right that almost anything in a GUI can be reproduced from command line, and a GUI is for the sake of convenience.

[eddelbuettel]

+1 for not advocating GUIs in intro documents.

Software Carpentry has a lot of well-thought out and empirically supported arguments why understanding the directs commands at the command-line is a necessary step.

UIs are all for convenience -- I am on Linux only and don't even have the GUI advocated by @yihui installed -- yet use the one offered by the editor I use (ie magit-mode) 95% of the time. The rest is split between the command-line and sometimes git via RStudio.

[yihui]

I'm not sure what you mean by "Linux only" -- did I mention apt-get install git-gui above?

I'm not saying people should not learn commands. Commands are important and essential, but that does not mean we have to use them all the time. I think we agree with each other that UIs are for convenience, but we have different emphasis on convenience. It seems convenience is more important to me than you. That is totally fine. We just use whatever makes ourselves comfortable. I guess magit-mode is not essentially different with the git gui approach: you press keys, and I click buttons, to do the same things underneath. So I guess there is no fundamental disagreement?

[eddelbuettel]

I am on Linux only was a (poorly-worded) shorthand to say that about 99% of my time in front of a computer is spent in front of a Linux machine (though maybe another OS may paint the terminal or application window), which most of the time I do control. And in two decades of Linux use I never installed that or another git GUI. So it was meant to qualify your "use git-gui" comment.

Now, I like GUIs. For the years spent with SVN I often also had one installed (eg KDE's SVN client is ok) while I still did most of my work from Emacs and/or the command-line. I like the RStudio git GUI. I used it for a few commits this morning when I also used roxygen2.

But my main point here is two-fold:

• Preferences differ, especially for UIs. So going out and saying you really ought to do things with this tool is not always the best way to convince people.
• Software Carpentry is adamant about understanding basics first. At the command-line. As I read this guide by @jtleek and the comment by @alyssafrazee, they tend to agree. Hence my '+1 for not advocating GUIs' above which started this.

[yihui]

Oh, I meant a GIT GUI, then I recommended git-gui, but I did not mean git-gui was the only tool that one must use. I only meant a helper so that a beginner could easily get started. Eventually they may learn the essentials if they care. It is not necessary that we have to understand every bits of the universe before we work on something. For me, 99% of the time I'm just doing git add + git commit, which is nice to do in a GUI instead of typing git add this that; git commit -m"updated foo bar". If that is the case for other people, I do not see how harmful it is to advocate GUIs to do this type of simple jobs. If it is not the case, I'm fine with whatever you advocate. I could be biased and wrong as always, and it is difficult to make decision for other people. I'd love to mention the possibility and existence of GUIs anyway (not necessarily forcing anybody to use them), instead of giving people an impression that software == commands in a window with a black background, which often sounds scary to beginners. Personally I use command-line heavily, but I do not insist command-line should be the first thing to teach. I could not imagine how I could possibly come to the world of Linux if I started from shell scripts on the first day.

[eddelbuettel]

I see. Both views can co-exist -- see eg In the beginning was the command-line (which is a great read in itself, but note the later development on the Wikipedia page).

GUIs can help when well designed; understanding what GUIs do and how to use them is aided from having worked the command-line. And IIRC I just saw Hadley state that he always drives git from the cmdline.

Preferences, as I said, differ. No size fits all, and many so-called truths just ain't.

[yihui]

Agreed.

[jtleek]

This is a great discussion. Thanks guys!