Skip to content

Commit c6bb7b7

Browse files
agentleciscoagentlecisco
committed
Update file list
1 parent 61d3cae commit c6bb7b7

12 files changed

Lines changed: 1275 additions & 0 deletions

‎_learn/00-github-for-docs-files.md‎

Lines changed: 258 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,258 @@
1+
---
2+
title: "GitHub for documentation sites"
3+
image:
4+
path: /images/learn/mikecogh-trains.jpg
5+
thumbnail: /images/learn/github-logo400x200.png
6+
caption: "Photo from [Flickr:mikecogh](https://flic.kr/p/pEn3RB)"
7+
---
8+
9+
Learning GitHub or any source control system backed by `git` for documentation sites takes some time and practice. This set of lessons uses the Terminal rather than the desktop application or the web site UI, though both are valid ways to do a GitHub workflow.
10+
11+
## Create a GitHub account
12+
13+
You can learn how to sign up for a GitHub account and pricing plans on [help.github.com](https://help.github.com/articles/signing-up-for-a-new-github-account/).
14+
15+
You can do all these docs-as-code tutorials with a free GitHub account.
16+
17+
## Learn basic Terminal and Git Bash commands
18+
19+
One great aspect of these developer workflows and tools means you have a lot of freedom to choose how you work. That said, for this choose-your-adventure series, we tend to think you already have Terminal commands memorized or you understand them. Whether you're on a Mac, Linux, or Windows, these come in handy.
20+
21+
Knowing the basics should help. Here's a short list:
22+
23+
* `ls` - List directory contents, `dir` is the equivalent in Windows.
24+
* `pwd` - Show working directory name, `cd ,` is the equivalent command in Windows.
25+
* `cd path/to/directory/` - Change to another directory. In Git Bash on Windows you can use `cd /c/project/`. If you need to change to a directory with spaces in the name, you must surround the path with double quote marks, such as `cd "C:\My Project\"`.
26+
* `cd ..` - Go up one directory.
27+
* `git status` - Shows the changes pending or shows if changes are already committed.
28+
* `git branch` - Lists all the local branches and indicates the current branch with an asterisk (`*`).
29+
* `git config -l` - Lists all the configuration for the local repo when it contains a Git repository.
30+
* `git init` - Sets up all the files for Git to be able to track a project as a repository. Init stands for initialize.
31+
32+
## More resources for learning Git and GitHub
33+
34+
As with any complex system, you want to practice using Git commands to learn the system well and also how to troubleshoot. Here's a great list of resources for both hands-on practice and reference.
35+
36+
* [GitHub Learning Lab](https://lab.github.com/) "Get the skills you need without leaving GitHub. GitHub Learning Lab takes you through a series of fun and practical projects, sharing helpful feedback along the way."
37+
* [GitHub Guides](https://guides.github.com/) - Guided tutorials about 3-10 minutes in duration.
38+
* [Git and GitHub learning resources](https://help.github.com/articles/git-and-github-learning-resources/)
39+
* [Five basic Git commands every beginner needs to know](https://www.theserverside.com/tutorial/Five-basic-Git-commands-every-beginner-needs-to-know)
40+
* [Troubleshooting connectivity problems](https://help.github.com/articles/troubleshooting-connectivity-problems/)
41+
42+
## Learn GitHub vocabulary
43+
44+
The terms sound confusing at first. Here's a list of vocabulary words to help you get through the initial learning curve.
45+
46+
<dl>
47+
<dt>branch</dt>
48+
<dd>
49+
<p>
50+
A parallel version of a repo within the repo that does not affect the primary or <code>master</code> branch. You can work freely in a branch without affecting the <i>live</i> version. After you make changes, you can merge your branch into the <code>master</code> branch to publish your changes.
51+
</p>
52+
<p>
53+
New contributors can confuse named directories, such as a cloned fork that is named after the original repo, and Git branches.
54+
</p>
55+
<p>
56+
You can instruct Git to base your branch on the <code>master</code> branch in upstream, origin, or another remote. For example, this command bases a new branch on the <code>master</code> branch in the <code>upstream</code> remote:
57+
</p>
58+
<pre class="small">$ git checkout upstream/master -b &lt;branch&gt;</pre>
59+
</dd>
60+
<dt>clone</dt>
61+
<dd>
62+
<p>
63+
A copy of a repo that lives on your computer instead of on a website's server.
64+
</p>
65+
</dd>
66+
<dt>commit</dt>
67+
<dd>
68+
<p>
69+
A point-in-time snapshot of a repo. Commits let you see the differences between changes. A commit is an individual change to a file or set of files. Every time that you save a file or a set of files, Git creates a unique ID, also known as the <i>SHA</i> or <i>hash</i>, that tracks the changes. Commits usually contain a commit message, which is a brief description of what changes were made.
70+
</p>
71+
</dd>
72+
<dt>downstream</dt>
73+
<dd>
74+
<p>
75+
A label for a remote URL, where a remote represents a place where code is stored. A downstream remote indicates an opposite of an upstream, or original, repo.
76+
</p>
77+
</dd>
78+
<dt>fork (noun)</dt>
79+
<dd>
80+
<p>
81+
A copy of the repo that is entirely yours in your namespace. A fork gives you a way to both contribute openly and get credit for your contributions.
82+
</p>
83+
</dd>
84+
<dt>fork (verb)</dt>
85+
<dd>
86+
<p>
87+
The act of making a forked copy of the repo.
88+
</p>
89+
</dd>
90+
<dt>issue</dt>
91+
<dd>
92+
<p>
93+
A way to submit a suggested improvement, defect, task, or feature request to a repo. In a public repo, anyone can create an issue. Each issue contains its own discussion forum. You can label an issue and assign it to a user.
94+
</p>
95+
</dd>
96+
<dt>organization</dt>
97+
<dd>
98+
<p>
99+
A collection of group-owned repositories.
100+
</p>
101+
</dd>
102+
<dt>pull request</dt>
103+
<dd>
104+
<p>
105+
A method of submitting edits that compares your changes with the original. Teams can view the comparison to decide whether they want to accept the changes.
106+
</p>
107+
</dd>
108+
<dt>push</dt>
109+
<dd>
110+
<p>
111+
Move your local committed changes to a remote location, such as <a href="http://www.github.com">GitHub.com</a>, so that other people can access them.
112+
</p>
113+
</dd>
114+
<dt>remote</dt>
115+
<dd>
116+
<p>
117+
A version of your project that is hosted on the Internet or on a network. The remote is usually connected to local clones so that you can sync changes.
118+
</p>
119+
</dd>
120+
<dt>repo</dt>
121+
<dd>
122+
<p>
123+
A collection of stored code or docs.
124+
</p>
125+
</dd>
126+
<dt>review</dt>
127+
<dd>
128+
<p>
129+
Perform a line-by-line comparison of a change and comment on improvements or suggest changes, much like a copy editor does for a newspaper article.
130+
</p>
131+
</dd>
132+
<dt>upstream</dt>
133+
<dd>
134+
<p>
135+
The primary label for the remote URL indicating the original repo where changes are merged. The branch, or fork, where you do your work is called <i>downstream</i>.
136+
</p>
137+
</dd>
138+
</dl>
139+
140+
141+
## Set up prompts (Terminal on MacOS or Linux)
142+
143+
While you're working in your Terminal window, it's great to always know which branch you're on by modifying your prompt to show the current `git` branch. To do so, put this snippet of code in your `~/.bash_profile` file:
144+
145+
```
146+
# Git branch in prompt.
147+
parse_git_branch() {
148+
git branch 2> /dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ (\1)/'
149+
}
150+
#export PS1="$ "
151+
export PS1="\u\ \W\[\033[32m\]\$(parse_git_branch)\[\033[00m\] $ "
152+
```
153+
154+
As an example, with this code in my `~/.bash_profile` file, my prompt looks like this while I'm working in a branch named `initial-content`:
155+
156+
```
157+
agentle\ choose-adventure-workshop (initial-content) $
158+
```
159+
160+
## Set up prompts (Git Bash on Windows)
161+
162+
Git Bash on Windows displays your current branch on the prompt for you.
163+
164+
One concept to remember here is that Git Bash uses Linux-like commands but the directory listings use forward slash (`/`) instead of back slash (`\`). You can change directories with commands like `cd /c/project/` where `/c/` represents your `C:/` drive on Windows.
165+
166+
## Set up your GitHub account for SSH access
167+
168+
To avoid entering your password every time you perform `git clone` or `git push` commands (it does get tedious), then set up an SSH key for your credentials on GitHub, and then always use the SSH reference rather than the HTTPS reference when you do a `git clone` command. You set up references with an SSH key as your identifier, and then you do not need to enter a password from the command line to authenticate to the GitHub site. The GitHub instructions for [Connecting to GitHub with SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) work great for this setup, and I highly recommend it.
169+
170+
## Create a new repository on GitHub
171+
172+
Before you get too far writing content for the site, get the directory set up for version control in a Git repo, and make some incremental commits.
173+
174+
1. Go to https://github.com and log in.
175+
1. In your browser, create a new repository in your user space or organization.
176+
1. In the browser, copy the SSH or HTTPS reference for the repo, such as: `git@github.com:annegentle/do-docs-as-code.git`.
177+
1. In the root directory, create a quick README file that contains only a header. For example:
178+
```
179+
$ echo "# do-docs-as-code" >> README
180+
```
181+
1. In the root directory, initialize the Git repo.
182+
```bash
183+
$ git init
184+
```
185+
1. Next, add all the files you want to have in the repo, as indicated with the period `.`.
186+
```bash
187+
$ git add .
188+
```
189+
1. Create a commit, or a point in time for the state of the current files in the directory.
190+
```bash
191+
$ git commit -a -m "Adds initial docs-as-code project"
192+
```
193+
1. In the Terminal window, type git commands to add a "remote" named "origin" and then paste in the SSH or HTTPS reference, such as `git@github.com:annegentle/do-docs-as-code.git`.
194+
```bash
195+
$ git remote add origin <paste the reference>
196+
```
197+
1. In the Terminal window, set the newly added remote as the upstream branch and push the initial commit to this new remote named origin.
198+
```
199+
$ git push --set-upstream origin master
200+
```
201+
202+
## Ignoring operating system files or generated files
203+
204+
In GitHub repos, you can place a `.gitignore` file that contains the file extensions or folder names that you want to keep out of source control. When a file extension or folder is in the `.gitignore` file, even when you use the `git add .` command, those files and folders are not added to the commit.
205+
206+
This exclusion is useful so that you do not have a lot of difficult merges on output HTML files or operating system tracking files.
207+
208+
For Sphinx, you want to ignore these files and folders to avoid merge conflicts:
209+
210+
```
211+
build
212+
.DS_Store
213+
```
214+
215+
For Jekyll, you want to ignore these files and folders:
216+
217+
```
218+
_site
219+
.DS_Store
220+
```
221+
222+
For Hugo, you want to ignore these files and folders. The `static` folder could be named `public`, depending on your configuration
223+
```
224+
static
225+
.DS_Store
226+
```
227+
228+
## Ignoring operating system files or generated files
229+
230+
In GitHub repos, you can place a `.gitignore` file that contains the file extensions or folder names that you want to keep out of source control. When a file extension or folder is in the `.gitignore` file, even when you use the `git add .` command, those files and folders are not added to the commit.
231+
232+
This exclusion is useful so that you do not have a lot of difficult merges on output HTML files or operating system tracking files.
233+
234+
For Sphinx, you want to ignore these files and folders to avoid merge conflicts:
235+
236+
```
237+
build
238+
.DS_Store
239+
```
240+
241+
For Jekyll, you want to ignore these files and folders:
242+
243+
```
244+
_site
245+
.DS_Store
246+
```
247+
248+
For Hugo, you want to ignore these files and folders. The `static` folder could be named `public`, depending on your configuration.
249+
```
250+
static
251+
public # depends on configuration
252+
.DS_Store
253+
```
254+
255+
## Additional resources
256+
[Learning Git and GitHub resources on help.github.com](https://help.github.com/articles/git-and-github-learning-resources/)
257+
[GitHub Guides](https://guides.github.com/)
258+
[Pro Git](https://git-scm.com/book/en/v2)

0 commit comments

Comments
 (0)