Search results

Activity 7c: Push local changes to the remote

Keep current with the latest trends in technical communication by subscribing to the I'd Rather Be Writing newsletter. 5,000+ subscribers

I'm giving an API documentation workshop in San Francisco, California, on November 19, 2019. Check it out on EventBrite and register today to receive a $100 early bird discount.

Activity 8c: Push local changes to the remote

  1. In a text editor, open the Markdown file you downloaded in the GitHub repository.
  2. Make a small change to the content and save it. For example, type your name below the page title.
  3. In your terminal, make sure you’re in the directory where you downloaded the GitHub project.

    To look at the directories under your current path, type ls (Mac) or dir (Windows). Then use cd {directory name} to drill into the folder, or cd ../ to move up a level.

  4. See what files have changed:

    git status
    

    Git responds:

    Changes not staged for commit:
    (use "git add <file>..." to update what will be committed)
    (use "git checkout -- <file>..." to discard changes in working directory)
    modified:   Home.md
    
  5. Add all the files to your staging area. The staging area contains all files that you want added to your next commit:

      git add .
    

    Git doesn’t automatically track all files in the same folder where Git has been initialized. Git tracks modifications only for the files that have been “added” to Git. By typing git add . or git add --all, you’re telling Git to start tracking modifications to all files in this directory. You could also type a specific file name here instead, such as git add Home.md, to just add a specific file (rather than all files changed) to Git’s tracking.

    After you run the git add command, Git adds the files into what’s called the staging area. As a sports analogy, the staging area is like your on-deck circle. These files are ready to be committed when you run git commit.

  6. See the changes set in your staging area:

      git status
    

    Git responds with a message indicating which files are on-deck to be committed.

    Changes to be committed:
    (use "git reset HEAD <file>..." to unstage)
    
        modified:   Home.md
    

    The staging area lists all the files that have been added to Git that you have modified in some way. It’s a good practice to always type git status before committing files because you might realize that by typing git add ., you might have accidentally added some files you didn’t intend to track (such as large binary files). If you want to remove this file from the staging area, you can type git reset HEAD Home.md to unstage it.

  7. Commit the changes:

      git commit -m "updated some content"
    

    When you commit the changes, you’re creating a snapshot of the files at a specific point in time for versioning.

    The git commit -m command is a shortcut for committing and typing a commit message in the same step. It’s much easier to commit updates this way.

    If you type git commit only, you’ll be prompted with another window to describe the change. On Windows, this new window will probably be a Notepad window. Describe the change on the top line, and then save and close the Windows file.

    On a Mac, a new window doesn’t open. Instead, the Vim editor mode opens up within the terminal. (“vi” stands for visual and “m” for mode, but it’s not a very visual editor.) I don’t recommend using Vim. If you get stuck in this mode and need to escape, press your Escape key. Then type q to quit. (See Vim commands here.) Normally, you want an external editor such as Sublime Text to open from your terminal. See Associating text editors with Git for details.

  8. Push the changes to your repository:

    git push
    

    Unless you set up automatic GitHub authentication, you will be prompted for your GitHub username and password. (Note that your username is your GitHub login ID, such as “jdoe,” not your friendly name, such as “John Doe.”)

    Note that when you type git push or git pull and don’t specify the branch, GitHub uses the default branch from origin. The default branch on GitHub is called master. Thus the command actually passed is git push origin master (which means “push these changes to the remote origin[al] repository, in the master branch”). Some developers prefer to specify the repository and branch to ensure they are interacting with the right repositories and branches.

    Your terminal window probably looks something like this:

    Terminal window with git commands
    Terminal window with git commands
  9. Now verify that your changes took effect. Browse to your GitHub wiki repository and look to see the changes.

Although there are many options for authoring and publishing tools with developer docs, at their core is a probably a Git workflow. The Git workflow can be more powerful and complex than any authoring tool. Interacting with Git might also be key for interacting with engineering repos to make edits to documentation that appears inside code.

22% Complete

22/146 pages complete. Only 124 more pages to go.



Donate?

Want to buy me lunch? Click the Donate button below to donate any amount through Paypal.