New/revised content is always/only considered new/revised in reference to the latest content in the feature/api_doc branch (I like to refer to this branch as my “Mainline” branch). As such, always author your new/revised content in a new branch spawned off of the feature/api_doc branch. The neat thing about this approach is that when you’ve completed and vetted your new content, you can update the docs using git merge (you simply check-out the mainline branch, and then merge-in the working branch).
If, while you worked on the new content (in its working branch), the mainline didn’t change, then the difference between the two branches will be just the commits on the working branch.
- If you merge the new content into feature/api_doc, it produces a Fast Forward. I.e,. feature/api_doc HEAD is advanced by one commit; it is a Merge Commit, and it contains all of the individual commits for incremental updates you made to the content in the working branch.
- you can switch back to mainline, and then pull the new content just by merging the commits from the spawned branch into feature/api_doc. This type of version tracking allows you to do things like undoing a content revision by simply rolling-back the commit.
If the cloned project has no develop branch
git branch -l develop
git checkout develop
git push origin develop
git checkout -b feature/doc_update
git push origin feature/doc_update
git branch --track -l migrate_comments
git checkout migrate_comments
If you’re not already on the feature/api_doc branch, then switch over to it
git checkout feature/api_doc
Check to make sure the working directory is clean (just in case).
git status
Update your local repository
git fetch
or
git fetch origin
You can omit “origin” if your repo is already setup with a default path-spec. To find out, try running “git fetch” and see what happens.
Spawn a new branch off of feature/api_doc
This git command for this, along with its options, is somewhat complicated. Here’s a breakdown of the pieces.
Set the command options
When creating a new branch, mark the start-point branch as upstream from the new branch. Note that track needs two dashes. I noticed that when I pasted the command line into the BASH, one dash was missing!
--track
Note: At this point, I’m not sure if you need to track the starting branch though. Tracking is useful when the spawned-from branch keeps growing due to other people’s commits. In that case, you, along with each of the other contributers should each keep your working directory up to date with respect to the spawned-from branch. Why? Because the assumption is that everyone contributing to the project always contribute to the current state of it. Think of it as a way to simulate the same experience for each contributor as if they were working on the mainline, alone. In your case, there are no other contributers. As such, the spawned-from branch should never change. That is unless you work on more than one content update at a time.
Ok then: You definately do need to use that tracking feature because you sometimes have to have more than on working branches going at the same time. This has already happened, and you didn’t realize that after you’d merged the first woking branch’s content update into mainline, that you then needed to synchronize the second working branch with it (i.e., that you needed to checkout the second working branch, and then execute a “git pull” from it).
-l
Create the branch’s reflog. This activates recording of all changes made to the branch ref, enabling use of date based sha1 expressions such as “<branchname>@{yesterday}”.
Issue the command
It’s easiest if you simply copy & paste this command line example into a new document in EditPad Pro; and then modify it accordingly.
Note: I chose not to create and switch to the new branch in one operation using “git checkout -b” – because I wasn’t sure if I could still include the options I needed (–track and -l). I’ll experiment with this and see if it’s possible, and if it is, I’ll recommend that approach.
git branch --track -l v1.4x_updates
Branch v1.4x_updates set up to track local branch feature/api_doc.
Checkout the new branch
And start documenting the new feature.
git checkout v1.4x_updates
Switched to branch ‘v1.4x_updates’
Increment the doc build number
%GITSOURCE%\python_rest_api\doc\user\v1\source\conf.py
Add the new content files to the local repo
Use Stage Changed.