Skip to content

Commit c69b30e

Browse files
kbromankbroman
committed
Add page on routine use of git
1 parent cf49486 commit c69b30e

2 files changed

Lines changed: 148 additions & 2 deletions

File tree

‎index.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,9 @@ There are many resources for git and github; my aim is to provide the
1212
minimal guide to get started.
1313

1414
- [Why?](pages/why.html)
15-
- [Your first time](pages/first_time.html): get account; set up ssh
16-
- Typical use: add, commit, push
15+
- [Your first time](pages/first_time.html): get github account;
16+
install git, set up ssh.
17+
- [Typical use](pages/routine.html): status, add, commit, push
1718
- Start new repository: from scratch; using current project
1819
- [Contribute to someone's repository](pages/fork.html)
1920
- I want to fix a bug in someone's project

‎pages/routine.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
layout: page
3+
title: Routine use of git and github
4+
---
5+
6+
The routine use of [git](http://git-scm.com) involves just a few commands:
7+
principally `add`, `commit`, and `push`, but also `status` and
8+
`diff`.
9+
10+
You can deal with git and github via a [GUI](http://mac.github.com/),
11+
but I prefer the command line, and so that's all I'll discuss.
12+
13+
### Add and commit
14+
15+
After you've made some small modifications to your project and
16+
checked that they work, use `git add` to indicate that they're ready.
17+
18+
$ git add R/modified.R man/modified.Rd
19+
20+
Then use `git commit` to add the modifications to the repository.
21+
22+
$ git commit
23+
24+
A text editor (e.g., [emacs](http://www.gnu.org/software/emacs)) will
25+
open; add a short message describing the changes.
26+
27+
To abandon your commit, exit the editor without adding text.
28+
29+
Note that `git add` is used to add completely new files as well as to
30+
“add” modifications to files that already exist in the
31+
repository.
32+
33+
The commit message should be short (40 or 60 characters) so it's easy
34+
to read in a list. For a more complex commit, write an initial line
35+
that is short and gives the overall idea, followed by as many lines as
36+
you want giving the details.
37+
38+
People tend to write commit messages in the present rather than past tense
39+
(eg, “Fix such and such” rather than “Fixed such and
40+
such”).
41+
42+
For a one-line commit message, you can skip the text editor business
43+
and just type
44+
45+
$ git commit -m "Fix such and such"
46+
47+
### Add everything
48+
49+
If you want to commit all of the modifications you've made, without
50+
having to explicitly “add” each file, you can skip the
51+
separate `add` and `commit` commands and just type
52+
53+
$ git commit -a
54+
55+
I try to avoid this, as it can lead to mistakes (committing more
56+
modifications then intended).
57+
58+
### Push to [github](http://github.com)
59+
60+
To push committed changes to github, type
61+
62+
$ git push
63+
64+
You don't need to do this every time, but do so after you've completed a batch
65+
of changes that you're thoroughly happy with and before you move on to
66+
something else.
67+
68+
Once you've pushed a commit, it's hard to take it away. But if you've
69+
not pushed it yet, you _can_ go back and scrap it and not have it part
70+
of your project's history.
71+
72+
But if you move on to something else without having pushed the
73+
changes, they may not get to github for months.
74+
75+
76+
### Status
77+
78+
You've made some changes to a project, but you're not sure what. Type
79+
80+
git status
81+
82+
It'll give you a list of files that have been changed, plus new
83+
files that haven't been formally added.
84+
85+
86+
### Diff
87+
88+
Exactly what changes have you made? Type
89+
90+
git diff
91+
92+
Or to see your changes to a particular file, type
93+
94+
git diff R/modified.R
95+
96+
It'll show you which lines have been added and which have been
97+
deleted.
98+
99+
100+
### How often to commit?
101+
102+
I prefer to do many small commits, each for a set of related changes:
103+
104+
- Think of something that needs to be fixed, or a feature to add.
105+
- Do the work.
106+
- Test that it is okay.
107+
- Add and commit.
108+
109+
Look at others' projects on github, to see what they do and what sort
110+
of commit messages they write.
111+
112+
### What to commit?
113+
114+
Don't include files that are derived from others. (Are you using
115+
[make](http://www.gnu.org/software/make/) or
116+
[rake](http://rake.rubyforge.org/)? You should be!)
117+
118+
For example, for a [LaTeX](http://www.latex-project.org/) manuscript,
119+
I wouldn't include all the .log, .dvi, .aux, etc., files. And if I
120+
have R code to generate a figure, I'll include the R code but not the
121+
figure.
122+
123+
Be careful about committing binary files, or really big files. Git
124+
works best with text files (like source code), as it keeps track of
125+
just the lines that were changed. With binary file, you'll save the
126+
entire file again with each change; that will clutter up your
127+
repository.
128+
129+
And once you've committed a big file to your repository, it's there
130+
forever, even if you use `git rm` to remove it later.
131+
132+
For big data files that are changing, you'll want to track a
133+
text-based version (not .xls!), and you probably will want to make a
134+
fully separate git repository for the data.
135+
136+
### .gitignore
137+
138+
The various files in your project directory that you're not tracking
139+
in git should be indicated in a `.gitignore` file.
140+
141+
You don't _have_ to have a `.gitignore` file, but if you don't, those
142+
files will show up every time you type `git status`.
143+
144+
Each subdirectory can have its own `.gitignore` file, too. And you
145+
can have a global such in your home directory, `~/.gitignore`.

0 commit comments

Comments
 (0)