Category: Git

Categories
Git

How to Use Git for Technical Writing

First you need to learn how to use Git, but then you need to find a way to use Git. I.e., Create a workflow that exploits Git’s strengths. This wasn’t obvious to me at first. Heck, I’d never even considered it until someone suggested I read this: A successful Git Branching Model. I’d been struggling with using Git, and I just figured that was a normal part of the learning curve.

Leverage branching

It turns out that you can do some pretty neat things with Git because of the way Git branching works (which is fundamentally different than what you’re used to). I now see branching in Git as its greatest strength. As a technical writer, I use branching in pretty much that same way that the devs use it. The documentation I write is always released in-step with the products (APIs and SDKs) that the docs cover.

Whenever I start a new doc project, I begin by getting an enlistment to the code base.

  1. Open a Git bash session. The Git command prompt automatically positions you in your Git Home directory (e.g., /src).

    "C:\Program Files (x86)\Git\bin\sh.exe" --login -i

  2. Get an enlistment to the project source code repository (i.e., Clone it locally). Here’s an example:

    git clone git@git.c11.3rdParty.com:android_mobile_verification.git

  3. Change directories; move down from the HOME directory to the project directory. Notice that you currently have the Master branch checked out.

    cd android_mobile_verification/

  4. Switch to the develop branch because that’s where all of the new bits are staged for the dev’s code, and for your new doc content.

    git checkout develop

  5. Fork off of (i.e., create a new branch off of) develop to use as a baseline branch for doc work that your team can then merge in with their latest code bits. My team and I settled on the convention of the branch name feature/api_doc.

    git branch --track -l feature/api_doc

Note: the use of the track option to mark the start-point branch as “upstream” from the new branch. The track needs two dashes. The l switch is used to create the branch’s reflog. This activates recording of all changes made to the branch ref. This allows me to create a paper trail (isolate and capture each change in a uniqe commit) for each and every change that I make to the docs.

  1. Checkout your new feature/api_doc branch.

    git checkout feature/api_doc

  2. Fork off of (see Fork a repo) feature/api_doc for authoring content for a specific version of the docs (e.g., maybe the devs added a new feature for the next version of the product). I usually give the new branch a name that indicates the product release number that the new content is for, but if I have no idea what that will be, then I choose something that appropriately indicates the state of the docs.

    git branch --track -l initial

  3. Checkout your new working branch.

    git checkout initial

  4. Author new content. I.e., Add, revise, and/or delete content.

  5. Merge the content into your baseline branch. As the product evolves, and the devs add new features, this step updates existing content with new content. When I complete the content, and after it’s been reviewd, and I’ve incorporated the revisions, I switch back to the feature/api_doc branch, and then merge the new content into it (i.e., I execute a git merge coming from the branch I was just in). These particular command options ensure that each of the iindividual commit ref log entries from the work I did in the other branch appear in the feature/api_doc as well (otherwise, they appear as just one merge commit).

    git merge -s recursive -X theirs initial

  6. All that needs to happen now is to make sure that the new content is merged into the devs new code bits. This entails two steps:

    1. Push the content upstream.
    2. Send a Pull Request (e-mail) to the Release Management team.
Categories
Git

Using Git with Eclipse

Background

I’m using Eclipse on Windows 10.

The Jgit API

Git functionality is programmatically exposed via the JGit API (Java library). To use Git in Eclipse, you install the plugin called EGit, which makes calls to the JGit library.

  • EGit – the EGit plugin is a Team Provider that implements the Git features in Eclipse.
  • JGit – the programming API Java library that implements the Git version control file access routines, network protocols, and core version control algorithms. JGit contains Git porcelain commands in the org.eclipse.jgit.api package.

Goal

To get the curent Git Commit SHA1 from the environment, you are going to have to write code that calls the JGit API.

The HEAD reference is a SHA1 of the current branch.

HEAD = ref: refs/heads/feature/api_doc
= C:\Users\Chris\src\python_rest_api.git\refs\heads\feature\api_doc

But it might not be what you want…

Remember that your work in progress resides in your Working Tree, and isn’t yet associated with a changeset.

As you edit your work, it currently resides in RAM. When you save your work, a snapshot of the current RAM image is copied into a file. When you stage your work, the current state of the file is converted into a git Blob, and is added to the Index to create the next changeset. When you commit your work, the Index becomes the current changeset (and is pointed to by the local HEAD ref).

If you want to find out which Change Set any topic in a doc set belongs to (perhaps by using View Source on the topic you’re currently viewing) – then you don’t want to know the Change Set SHA1 of HEAD if you simply built the docs as a matter of course of writing/editing. You’ll want the SHA1 of the commit that corresponds to the final committ, which you won’t get until you’ve completed the writing work.

JGit cookBook

This project has example code that demonstrates how to develop code using JGit.

Grab it

git clone git://github.com/centic9/jgit-cookbook

Build it and create Eclipse project files

mvn dependency:sources eclipse:eclipse package

Run it

Import the project into an Eclipse workspace and execute the snippets there.

Categories
Git installation

Using the SSH Transfer Protocol

Setting-up by copying existing keys from another machine

Simply copy the contents of the folder %USERPROFILE%.ssh from your source computer, to the same location on your destination computer. The folder contains five files:

known_hosts
id_rsa.pub
id-rsa
github_rsa.pub
github_rsa

First-time Setup

Note: When you get to step where you are to add your SSH key to GitHub, email your key to the git administrator instead.

Passphrase

Land Cruiser

Your private key

Saved in: C:\Users\Chris.ssh\id_rsa

Your public key

Saved in: C:\Users\Chris.ssh\id_rsa.pub.

Categories
Git installation

To Change the Root Directory of your Git Installation

  1. Add a new directory named “src” to your Git root directory (C:\Users\Chris). I.e., C:\Users\Chris\src
  2. Create a new environment variable that points to it:
GITSOURCE = %HOME%\src

  1. Right-click the icon for Git Bash, and open it’s properties page.

  2. Set the “Start in value”=%GITSOURCE%

    (%HOMEDRIVE%%HOMEPATH%)

Git Bash Properties

Target: “C:\Program Files (x86)\Git\bin\sh.exe” –login -i”

For the x64 version: “C:\Program Files\Git\git-bash.exe” –cd-to-home

Categories
Git installation

After you Install Git

You must configure your Git installation for first use. For more information, see Getting Started – First-Time Git Setup.

Setup your identity

Configure your username.

git config --global user.name "John Doe"

Give the executables admin privileges

Edit the Properties of the following two executable files, and give them Admin Privileges for All Users.

C:\Program Files\Git\bin\sh.exe
C:\Program Files\Git\mingw64\bin\wish.exe

Add the git bash icon to the taskbar

Check to see if there is already an icon for it on your desktop. If there is, then right-click it, and select Display on Taskbar.

Add the git GUI icon to the taskbar

Note: If you already have a git bash open, then simply type “git gui” to start the Git GUI. Type “gitk” to start the Git Branch Visualizer.

Target: “C:\Program Files\Git\bin\wish.exe” “C:\Program Files\Git\libexec\git-core\git-gui”

Start in: %GITSOURCE%

Set the default.push behavior

Note: If you’ve done this before, then you don’t have to do it again.

Set this to simple, which will push the current branch to its upstream counterpart, but only if there is an upstream counterpart.

git config --global push.default simple

Files to store in git

For java 3rd party

C:\Users\Chris\src\java_3rdParty\

Project level files

.classpath
overview.html
.project
ant.properties
README.rest
.gitignore

There are two places that you can store ignore lists.

  • In a file named “.gitignore” in the project’s root directory. This is for files that no one on the team wants tracked.
  • In a file named “exclude” in the project’s $GIT_DIR/info/exclude. This is for files that you want ignored for your own personal files, that you don’t want to share with the rest of the team.

Syntax

In Git, back-slashes (\) are used to escape git’s special symbols (e.g., ! becomes \! for a filename spec that begins with a bang).

In Git, forward-slashes (/) are used to denote a level in a path structure. You don’t have to include the trailing slash in a folder name. Git ignores the directory, and everything it contains. I.e., the rest of the branch.

To exclude all files of a particular type, you must precede the filespec with an asterisk. E.g., “.pyc” won’t work. “*.pyc” will work.

Example

git ls-files --others --exclude-from=.git/info/exclude

Generated Files

doc\\user\\v1\\build

Personal Files

doc\\CJB_Custom_Dictionary.txt

Merge changes from another branch into this branch

git merge --no-ff scrub_verify_code

Push changes from a local branch to the same branch on the remote

git push origin feature/api_doc

Note: You must specify the branch because if you don’t, then Git attempts to push all branches.

Setup beyond compare as the external merge tool

Note: This only works from the Git bash. I was hoping to get it to work from the Git GUI, but I kept getting an error when I right-clicked the diff pane, and select Merge.

Create a new environment variable

MERGEHOME=C:\Program Files (x86)\Beyond Compare 4

Path it:

;%MERGEHOME%\

Note: If you use the Git for Windows’ bash command prompt instead of the default Windows command prompt, then you need to escape the $ character with .

Upadate the global .gitconfig file

Update your user configuration file (%USERPROFILE%.gitconfig) with the following information.

[diff]
tool = bc
[difftool “bc”]
path = C:\Program Files (x86)\Beyond Compare 4\BComp.exe
[merge]
tool = bc
[mergetool “bc”]
cmd = “C:\Program Files (x86)\Beyond Compare 4\BComp.exe” “$LOCAL” “$REMOTE” “$BASE” “$MERGED”

Running a merge using beyond compare

You need to merge when you pull (or merge) the latest version of the master branch into your branch. Git downlads a copy of the remote’s copy of the current branch, and then adds it to your repo. In your repo, it’s just another branch, and it’s named “upstream/master”.

git fetch upstream

Merge

git merge upstream/master

When you execute this command from the Git Bash:

git mergetool

To launch a 3-way merge on a particular file, use the command:

git mergetool foofile.txt

What happens when you run a merge

When you launch the Git Mergetool, the Beyond Compare 4 GUI appears, with the four 3-way merge panes loaded with:

Left Pane
Your version.
Middle Pane
The last version before you made your changes, and before it was changed in the remote.
Right Pane
The version in the remote.
Bottom Pane
Your new version – which will contain the merged content.
Categories
Git installation

Git: What to Download and Install?

It seems like there are several different Git applications available, but after digging deeper into this issue, I discovered that the “two best choices” – are actually the same thing. If you click “Download” on both of these web sites,

You get the exact same file (and you get it from the same web server).

MinGW

MinGW, a contraction of “Minimalist GNU for Windows”, is a minimalist development environment for native Microsoft Windows applications. MinGW provides a complete open source programming tool set that is suitable for the development of native MS-Windows applications, that do not depend on any 3rd-party C-Runtime DLLs. It does depend on a number of DLLs provided by Microsoft themselves, as components of the operating system; most notable among these is MSVCRT.DLL, the Microsoft C runtime library. Additionally, threaded applications must ship with a freely distributable thread support DLL, provided as part of MinGW itself.

MinGW compilers provide access to the functionality of the Microsoft C runtime and some language-specific runtimes. MinGW, being Minimalist, does not, and never will, attempt to provide a POSIX runtime environment for POSIX application deployment on MS-Windows. If you want POSIX application deployment on this platform, please consider Cygwin instead.

MSys

MSys is an environment for Windows offering a Unix-type shell and a Perl interpreter. Because many parts of Git are still not builtins programmed in C, but instead shell and Perl scripts, Git for Windows needs such an environment.

msysGit

For historical reasons, the development of Git for Windows requires a development environment that resembles Unix more than Windows, and this development environment is called msysGit.

Git for Windows

Git for Windows is the installer that most people should download to be able to use Git on Windows.

Git setup

Download and Install the latest version of git. I believe this gives you the hard-core command-line version. This version is the one that also includes the GUI apps that you’re used to – git-gui and gitk (for visualizing the branches in a repo (sort of like looking at a map of the London Tube)).

URLs

Home Page: http://git-scm.com/

There is a download link on the home page – use it to download and install git on your computer. Note: the download link automatically targets your platform (i.e., it’s for Windows if you’re on Windows, Linux if your on Ubuntu, and OS/X if you’re on Yosamite).

To install Git

Install the Latest Stable Release.

Download and run

  1. Click the “Download for Windows” in the image of the monitor on the right (http://git-scm.com/download/win).
  2. I chose the 64-bit version.
  3. In the Download Toast Window, click Run.

In the git setup wizard

  1. Install to: C:\Program Files\Git
  2. Select Components: I chose everything (Start Menu Folder: Git).

Adjusting your PATH environment

Choose the default option: Run Git from Git Bash

Configuring the line ending conversions

Choose Checkout Windows-style, commit UNIX line endings.

Environment variables

Source folder

Set the Environment Variable that points to the folder you want to use as the root folder (where Git will save all of your cloned enlistments). E.g.,

GITSOURCE=%USERPROFILE%\src

Default editor

Set the environment variable for your editor (mine is EditPad Pro).

$EDITOR = C:\Program Files\Just Great Software\EditPad Pro 8\EditPadPro8.exe

 

Categories
Git

Common Git Tasks

To contribute to a project hosted on GitHub

This procedure assumes that you cannot make commits to the origin repo. I.e, that you must issue a Pull Request from the Admin of the Origin repo.

  1. Visit the project repository on GitHub.
  2. “Fork” it. This creates your own copy of it on GitHub – under your GitHub account. This copy is “downstream” from the original project repository, which is in turn, “upstream” in relation to this copy.
  3. “Clone” a copy of your GitHub-hosted version of this repository. This creates a local working copy of the repository on your hard drive. In relation to this working copy of the repository, your GitHub-hosted copy is a remote (which you can refer to as “origin” (refs/remote/origin/)). The original repo that you forked from is now Upstream from Origin. To get your revisions into the upstream repo, you must issue a pull request.

Note: You end up with two enlistments: one under your account on GitHub, and another on your local hard drive.

To clone a repository

In Source Depot, this would be called “branching”. In Git, Cloning is much simpler, and yet, more powerful. Cloning produces a “working copy” of a project repository on your local hard drive. This is where you add/edit/delete source files.

To merge a branch

This updates the current branch with the difference in content (Git repository directory structure, directory contents, files, and file contents) between itself and another branch in the same repository.

To perform a merge:

  1. Switch to the branch (Checkout) that you want to receive the new content.
  2. Update your local copy of that branch (fetch).
  3. Run the merge.

In the simplest case, there are no conflicts (e.g., you’re just adding content).

For example, consider the case where the other branch contains the exact same files, except one of them contains an extra class definition. After merging them, the current branch would also contain the new class definition (as well as any new content that is not in the second branch).

To update your repository

Fetch

Get the remote data, and add it to my repo as another branch (i.e., as a remote branch).

Note: Remote branches don’t appear locally, automatically. To actually get a local copy, you need to perform:

git checkout remote/<branchname>

Pull

Fetches the remote data, and merges it in with the contents of the current branch (performs two steps in one).

Categories
Git What is Git?

Git: Key Concepts

Git’s unusual relationship with the file system

Git plays a kind of slight-of-hand with the contents of your local file system. The contents of all of the branches in a Git repo appear to occupy the same place on your local disk. No other CVS does this, so it’s a paradigm shift that you need to comprehend to really understand the nature of Git. E.g., You check-out a particular branch, and then cd to one of its directories. You open a file in that directory (called index.rst say), and it contains one sentence of text. Next, you checkout another branch, and open the same file, in the same directory. This time however, the file contains an entire paragraph of text (for example) – same place on the hard drive, but different contents.

Git repository

A Git repository contains all of the information needed to transform its working directory file structure into a snapshot of any commit in any branch. Take a look in any repository’s “.git” directory – especially the “objects” directory, to see the bits that Git assembles it from. By convention, I store my repositories in %USERPROFILE% in a directory called src.

Git branch

A branch holds a set of incremental changes to files and folders in a repository (snapshots, HSAs). Internally, Git represents branchs as tree objects. Branches are identified by a reference on the last commit. At any time, the state of the files that you’re working on belong to a snapshot called “the Working Directory”. As your work progresses, you frequently save your work in progress (using the file system save feature). Each time you save your work, Git updates a branch snapshot called “index”. If you have staged changes, and you create a new branch and then switch to it, the state of the staging area isn’t changed. You can use the index like any ref. I.e., you can diff between index and the last commit.

Git changeset

Leverage Git branching to help you manage documentation updates

In the project I was workikng on, my mainline on Origin was a branch called feature/api_doc. I’d merge my completed work into this branch, and then push it to origin.

Note: Don’t use feature/api_doc for your work in progress.

Instead, create a new branch for the new work (e.g., named after the new feature), and complete the work in that branch, and then merge the new branch into feature/api_doc – after you’ve completed the update (which includes draft, technical review, update content per technical review, second review, etc.). Then you Push your merge commit up to origin, and then send a pull request to the lead dev to have your new content merged into mainline.

Base the new branch on feature/api_doc.

  1. Checkout feature/api_doc.

  2. Update feature/api_doc (Pull) to ensure that you’re in synch with origin.

  3. Create a new branch (e.g., git branch -b Verify_Code_Sample_Update)

    1. In Eclipse, switch to the Git Repository view.

    2. Right-click the repository that you want to create the new branch in.

    3. Click Switch To > New Branch.

    4. Enter a name for the new branch (e.g., Verify_Code_Sample_Update).

      No Pull Strategy.

      Checkout new branch.

      When you commit content to this branch, Git manages a reference (SHA) to it named: refs/heads/Verify_Code_Sample_Update.

Categories
Advantages Git

The Advantages of Switching to Git

  • Merging branches is much simpler in Git. You can think of branches as alternate timelines (or alternate universes).
  • It’s much easier to keep stable work and work in progress, separate.
  • Git separates the act of committing new code from the act of inflicting it on everybody else. I.e., you can commit your changes locally, but the rest of the team won’t see them until you Push your changes up to Origin.
  • If you’re used to having one big gigantic repository for the whole company, where some people check out and work on just the subdirectories that they care about, this isn’t a very good way to work with Git—you’re better off having lots of smaller repositories for each project.
  • There is no central repository, only an agreed-upon funnel-point (a remote repository named Origin).
  • Git doesn’t use the concept of Revisions. Instead, it uses the concept of Changesets (also known as commits).
  • A commit is a snapshot of the state of a branch. as it existed at a particular point in time.
  • Like a commit, a branch is a version of a repository, but it contains an alternate lineage of commits that differ from that of master (it diverges from master).
  • A commit is identified by a hash of its contents, and the resulting hash code (a forty digit hex value) becomes the symbolic reference – its “Reference ID”.
  • So for example, when you edit a sentence in a text file within a particular branch, not only have you altered that one file, you’ve also altered the entire branch.
  • When you Commit the change, a new hash code is generated (based on the new hash of the branch snapshot), and that hash code becomes the unique identifier for that set of changes (well, one change in this case). A changeset generally contains more than just one change to one file. In practice, you hold-off on “Committing” until you’re done making a series of related changes. E.g., updating all topic source files with the revised ordering of JSON nodes with the JSON dictionary returned in responses (in the Examples section of each topic).
  • Commits also contain a back-pointer to the previous commit. Such recursive linking turns your set of commits into a linked list (a directed graph). Viewed as such, this link information represents the lineage of your branch. It allows you to see the entire history of your branchy all the way back to its beginning (where it diverged, and ultimately – when it was cloned).
  • It also allows you to identify where in the lineage a particular change was introduced, and it allows you to revert back to any branch state.
  • Git allows you to use a short form of the hash to specify a commit. The convention is to use the first six digits, but you can use less if you project is small. E.g., you can use 48b217 to refer to 48b2179994d494485b79504e8b5a6b23ce24a026.
  • The “current version” of your repository is always the latest commit (the one that the HEAD reference points to), and the hash of it is always placed at the end (the tip) of the linked list.
  • HEAD is a symbolic reference to (the Reference ID of) the commit at the end of the branch. It identifies what the current repository is pointing to. It marks the branch that is advanced with the next commit.
  • The command ‘git branch’ displays a list of branches in your repository, and it marks the current branch with an asterisk next to its name.
  • Creating new branches in Git is much simpler than in centralized version control systems. Branching is encouraged in Git – because it’s built on a very simple concept. To create a new branch in Git, you simply add a new branch label to the commit that HEAD point to.
  • You can switch to any branch just by changing the commit that HEAD points to, to point to the commit with that branch label. In Git, you use the git checkout command to switch branches (which is confusing for CVCS users because checkout doesn’t mean what they’re used to).
  • In Git, you’re encouraged to create branches way more often than in centralized VCSs. As a result, you can think of Git branches as throwaway changesets.
  • The default branch is called master.
  • You synchronize your repository with a remote repository using git push and git pull. You use push to update the remote repository with your latest bits, and you use pull to update your repository with the remote repository’s changes. Either way, when you’re done, both repositories contain the same thing (assuming you pulled first).

Note: For this reason, always pull before you push.

  • If you clone an existing repository, then a remote named Origin is automatically set up for you. You keep up-to-date with what’s happening on the remote repository by executing git pull origin. “Origin” is the name of the default remote, but you can have many remotes per repository. E.g.,
git remote add github http://github.com/alblue/babel.git
git push github
  • Git allows you to “Commit” files, much like any other version control system. Each commit can be a single file, or many files; and a message goes along with it.
  • Unlike other VCS’s, Git has a separate concept of a staging area, or Index. When you want to track a file (i.e., add it to the repository), you stage it (i.e., add it to the index). In other words, when you stage a file (or files), you can then commit them to the respository. The index contains a set of files to be committed. You can think of it as an active changeset; as you’re working on multiple files, you want only some changes to be committed as a unit. First, you git add the files to the Index, then you git commit subsequently.
  • git add – to add untracked files for change tracking, and to update already staged files.
  • git commit – commits the staged files. Creates a commit object, and adds it to the graph.
  • You have to git add a file in order for it to be tracked. After you add it to the staging area, you can keep working on it – you just have to continually save it to the file system. When you’re finished with the file, you can then commit it. Once committed, you can then push it up to the origin repository.
  • When you run git fetch, you get the newest commits from Origin, but they are not merged into your current branch. Just the remote refs are updated. I.e., all of the remote branches are updated in your local repository.
  • git fetch followed by git merge = git pull
  • A fast-forward is the simplest kind of merge (i.e., with no conflicts). It just brings your branch up-to-date with the same branch on a remote repository (origin). All it does is download the changesets that exist on the remote, that don’t exist in your repository, and then it updates your “HEAD” to point to the new branch tip.
  • Rebasing simplifies the repoisitory tree structre. It replays a series of commits upon a specified commit. ‘git rebase’ – Reapplies a series of changes from a branch to a different branch, and resets the head of that branch to the result. Rebasing replants your tree – but do it on local branches only!
Categories
Git What is Git?

The Problems with Git that You’re Likely to Encounter at First

You’ll make notes about what Git is, how it works, and how to use it. But as you build your knowledge, parts of it will evolve-as you have epiphanies.

You’ll execute Git commands, thinking that because they have the name names as the old system, that they do pretty much the same things – but they actually do quite different things. And Git commands produce different results depending on the context.

For example, you’ll spend three months thinking that git checkout is just like a Source Depot checkout, without really knowing what git checkout does. Here’s the difference:

You can switch to any branch just by changing the commit that HEAD points to. In Git, you use the “Checkout” command to switch branches (which is confusing for CVCS users, because it doesn’t mean what you think).

You’ll try to branch the Source Depot way, and you’ll get confused because it produces inexplicable results, and it didn’t work so well because you really should have been branching the Git way – by cloning repositories, not by trying to do the things that work in Source Depot.

In GitHub (an online Git host), the term “Fork” is used to refer to a clone of a repository – cloned under your account on GitHub. This is confusing because you’re apt to think of a fork as just another branch. You use Fork when you work on a project that you don’t have permission to write to. To Push your changes up to Origin, you issue a Pull Request (which gets someone with write permissions to integrate your changes into the mainline).