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.
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.
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.
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.