Allows you to use mouse clicks to perform git commands.
Allows you to use mouse clicks to perform git commands.
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.
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.
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
Get an enlistment to the project source code repository (i.e., Clone it locally). Here’s an example:
git clone firstname.lastname@example.orgParty.com:android_mobile_verification.git
Change directories; move down from the HOME directory to the project directory. Notice that you currently have the Master branch checked out.
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
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.
Checkout your new feature/api_doc branch.
git checkout feature/api_doc
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
Checkout your new working branch.
git checkout initial
Author new content. I.e., Add, revise, and/or delete content.
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
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:
I’m using Eclipse on Windows 10.
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.
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.
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.
This project has example code that demonstrates how to develop code using JGit.
git clone git://github.com/centic9/jgit-cookbook
mvn dependency:sources eclipse:eclipse package
Import the project into an Eclipse workspace and execute the snippets there.
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
Note: When you get to step where you are to add your SSH key to GitHub, email your key to the git administrator instead.
Saved in: C:\Users\Chris.ssh\id_rsa
Saved in: C:\Users\Chris.ssh\id_rsa.pub.
GITSOURCE = %HOME%\src
Right-click the icon for Git Bash, and open it’s properties page.
Set the “Start in value”=%GITSOURCE%
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
You must configure your Git installation for first use. For more information, see Getting Started – First-Time Git Setup.
Configure your username.
git config --global user.name "John Doe"
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
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.
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%
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
.classpath overview.html .project ant.properties README.rest .gitignore
There are two places that you can store ignore lists.
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.
git ls-files --others --exclude-from=.git/info/exclude
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.
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.
MERGEHOME=C:\Program Files (x86)\Beyond Compare 4
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 .
Update your user configuration file (%USERPROFILE%.gitconfig) with the following information.
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
git merge upstream/master
When you execute this command from the Git Bash:
To launch a 3-way merge on a particular file, use the command:
git mergetool foofile.txt
When you launch the Git Mergetool, the Beyond Compare 4 GUI appears, with the four 3-way merge panes loaded with:
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, 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 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.
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 is the installer that most people should download to be able to use Git on Windows.
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)).
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).
Install the Latest Stable Release.
Choose the default option: Run Git from Git Bash
Choose Checkout Windows-style, commit UNIX line endings.
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.,
Set the environment variable for your editor (mine is EditPad Pro).
$EDITOR = C:\Program Files\Just Great Software\EditPad Pro 8\EditPadPro8.exe
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.
Note: You end up with two enlistments: one under your account on GitHub, and another on your local hard drive.
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.
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:
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).
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>
Fetches the remote data, and merges it in with the contents of the current branch (performs two steps in one).
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.
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.
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.
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.
Update feature/api_doc (Pull) to ensure that you’re in synch with origin.
Create a new branch (e.g., git branch -b Verify_Code_Sample_Update)
In Eclipse, switch to the Git Repository view.
Right-click the repository that you want to create the new branch in.
Click Switch To > New Branch.
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.
Note: For this reason, always pull before you push.
git remote add github http://github.com/alblue/babel.git git push github