sansstatusmonitor

Revised10/7/13AccuRevGitCentricUser'sHelpVersion2013.
2CopyrightandTrademarksCopyrightAccuRev,Inc.
1995--2013ALLRIGHTSRESERVEDThisproductincorporatestechnologythatmaybecoveredbyoneormoreofthefollowingpatents:U.
S.
PatentNumbers:7,437,722;7,614,038.
AccuRevandTimeSafeareregisteredtrademarksofAccuRev,Inc.
AccuBridge,AccuReplica,AccuSync,AccuWork,Kando,GitCentric,andStreamBrowseraretrademarksofAccuRev,Inc.
Allothertradenames,trademarks,andservicemarksusedinthisdocumentarethepropertyoftheirrespectiveowners.
GitCentricUser'sHelpiiiTableofContentsPreface.
viiAudienceviiUsingThisBookviiTypographicalConventionsviiiContactingTechnicalSupport.
viiiLicenseIssues.
viiiOtherSupportIssues.
viiiOtherResources.
ix1.
ConceptsandOverview.
1WhatisAccuRevGitCentric1WheretogoforMoreInformation1ANoteAboutTerminology.
2BasicArchitecture.
3GitCentricUsers4GitCentricAdministratorsandMappingBranchestoStreams.
4BasicRules5MappedBehavior.
5BestPracticesWhenPlanningYourInstallation5KeepingGitMergesandAccuRevPromotesinSync.
6BestPracticeforKeepingMergesandPromotesinSync7ScenariosforMappingMultipleRepositoriestoaSingleStream7MultipleReposandMultipleServers.
8AccuRevReplicaServerRestriction9ConfiguringforSecurity.
9ConfiguringMultipleGitReposwithAccuRevandEACLs.
10GettingStarted112.
Howto.
13ProceduresforAllUsers.
13GetStarted13DefineandDisplayaSiteHeaderorFooterforGerritCodeReview.
17ConfiguretheCloneforCodeReview(Optional)18ConfiguretheCloneforDirectPush18TroubleshootGitCloneIssues.
18ConfigureGitCentric21RemoveaBranch.
23RemoveaRepository.
23ANoteAboutAccuRevDepots23ImportaSnapshotoftheLatestHeadsintoAccuRev.
24ImportCompleteGitHistoryintoAccuRev[BETAonly]25GitCentricUser'sHelpivGeneralProcedureforSettingACLs.
30ConfiguringACLsforCodeReview.
32ConfiguringGitCentricACLsforDirectPush.
34SpecifytheServerandServiceAccount34MaptheBranchtotheStream36RegisteringanAccuRevServer.
39ConfiguringtheAccuRevServer.
40ConfigureMultipleAccuRevServers41ToViewandAccessGroups.
42AddaGroup42AddaMembertoaGroup.
42AccuRevGroups.
43AllowingSelf-Reviews.
44DisablingCodeReview.
44Overview.
45RegisteringtheGitCentricBridgeSSHKeywithGerrit.
45Modifyingthereplication.
configFile.
45AccuRevtoGit47GittoAccuRev473.
MyAccount49MenuOptions49Profile49WatchedRepositories(Projects)50ContactInformation.
51PublicKeys.
51AccuRevServers51HTTPPassword.
51People524.
CodeReview53OverviewofGerritCodeReview53DifferencesfromStandaloneGerritCodeReview53CodeReviewforUsersofDifferingBackgrounds.
54GerritCodeReviewandAccuRevMappings.
54Troubleshooting555.
Administration57Repositories58ToCreateaNewRepository.
58ToConfigureanExistingRepository58SupportforHooks.
63People.
64AccuRevServers.
65ANoteabouttheCLIPathSetting.
65GitCentricUser'sHelpvA.
ThekandoMaintainUtility.
67UsingkandoMaintain.
67BackupandRestore67kandoMaintainCommandReference67Commands.
67Options.
69GitCentricBridgeConfigurationSettings71Examples.
71B.
BackupandRestore.
73TheBackupProcess.
73WhataretheGitCentricDatabases73BestPractices.
73BackingUpGitCentric74WhatGetsBackedUp74WheretheBackupFileGetsCreated.
74BeforeYouBegin74HowtoBackUpGitCentric74RestoringGitCentric.
75RestoreScenarios.
75BeforeYouBegin76HowtoRestoreGitCentric76C.
Command-LineReference.
79BasicSyntax79SpacesandQuoting79CLIExample.
85D.
GitCentricGlossary.
87Index.
95GitCentricUser'sHelpviGitCentricUser'sHelpviiPrefaceThisdocumentservesasboththeon-linehelpandtheUser'sGuideforAccuRevGitCentric.
ThisdocumentationcoversbothGitCentricenduserandadministratoraudiences.
GitCentricprovidesmostfunctionalitythroughaWebUI,butalsoprovidesthreeadministrativeCLIcommands.
AudienceThisdocumentisintendedforGitCentricendusersandadministrators.
EndusersareassumedtobefamiliarwithGitsourcecontrol,andpossiblyGerritCodeReview.
AdministratorsareassumedtobefamiliarwiththesetopicsandalsowithLinuxoperatingsystems,aswellasAccuRevandAccuWorkconcepts.
UsingThisBookThisbookassumesyouarefamiliarwithyouroperatingsystem(s)andtheircommands,aswellaswithAccuRev,AccuWork,andGit.
Thefollowingtablesummarizesthechaptersandappendixesinthisbook.
ChapterDescriptionAudienceChapter1ConceptsandOverviewIntroducesbasicGitCentricconceptsandarchitecture.
EndusersandadministratorsChapter2Howto.
.
.
ProvidesaseriesofcommontasksthatyouperformtoconfigureanduseGitCentric.
EndusersandadministratorsChapter3MyAccountProvidestheabilitytoregisteryourselfwithGitCentric,andtosetyourpreferencesandcontactinformation.
EndusersandadministratorsChapter4CodeReviewGivesyouaccesstooptionalthird-partyGerritCodeReviewfunctionality.
EndusersandadministratorsChapter5AdministrationSummarizesthefeaturesforconfiguringandmaintainingrepositories,groups,andAccuRevservers,includingsecurityconfiguration.
Provideslinkstoconceptualandtask-basedsectionsofthisdocument.
AdministratorsAppendixAThekandoMaintainUtilityDescribesthecommandlinekandoMaintainutilityforupgradingandadministeringtheGitCentricdatabase.
AdministratorsAppendixBBackupandRestoreSummarizesproceduresandbestpracticesforbackingupyourGitCentric-relatedrepositoriesanddatabasefiles.
AdministratorsviiiGitCentricUser'sHelpTypographicalConventionsThisbookusesthefollowingtypographicalconventions:ContactingTechnicalSupportAccuRevoffersavarietyofoptionstomeetyourtechnicalsupportneeds.
ForcompleteinformationaboutAccuRevtechnicalsupportservices,visitourWebsite:http://www.
accurev.
com/support.
htmlLicenseIssuesIfyouarehavingtroublewithalicenseforyourAccuRevproduct,visittheLicenseSelfHelppagefirsttoseeifthereisasolutionforyourproblem:http://www.
accurev.
com/support/license-self-help.
htmlOtherSupportIssuesToobtaintechnicalsupportforanAccuRevproduct:Gotohttp://support.
accurev.
com/OrwriteAccuRevtechnicalsupportatsupport@accurev.
comWhenyoucontactAccuRevtechnicalsupport,pleaseincludethefollowinginformation:TheAccuRevproductandversion(forexample,AccuRev5.
4.
1,GitCentric2013.
1)TheoperatingsystemAppendixCCommand-LineReferenceSummarizesthesyntaxandusageoftheGitCentricadministrationcommands,typicallyusedforscriptingadministrativefunctions.
Note:Althoughthesecommandsaregenerallyconsideredadministratorcommands,anyregisteredusermayusethels-repocommandtoviewtherepostowhichtheyhaveaccess.
AdministratorsAppendixDGitCentricGlossaryAlistofGitCentric-relatedtermsandtheirdefinitions.
EndusersandadministratorsConventionDescriptionbluesans-serifUsedforsamplecodeoroutput.
boldUsedforcommandnames,andbuttonnamesintheGitCentricuserinterfacelightitalicUsedforemphasis,booktitles,andforfirstuseofimportanttermsblueitalicIdentifiesahyperlink(toapageorWebURL,forexample)ChapterDescriptionAudienceGitCentricUser'sHelpixAbriefdescriptionoftheproblemyouareexperiencing.
BesuretoincludewhichAccuRevinterfaceyouwereusing(Webuserinterface,JavaGUI,orCLI),anyerrormessagesyoureceived,whatyouweredoingwhentheerroroccurred,whethertheproblemisreproducible,andsoon.
Adescriptionofanyattemptsyouhavemadetoresolvetheissue,includingusingtheresourcesdescribedinOtherResources.
Asimpleassessmentofhowtheissueaffectsyourorganization.
OtherResourcesInadditiontocontactingAccuRevtechnicalsupport,considertakingadvantageofthefollowingresources:AccuRevKnownProblemsandSolutions--http://www.
accurev.
com/support/kps.
htmlTheAccuRevKnownProblemsandSolutionspagedescribesknownproblemsinreleasedversionsofAccuRevproducts.
TheTroubleshootingsectionoftheGitCentricInstallationandReleaseNotes.
AccuRevUserForum--http://www.
accurev.
com/ubbthreads/TheAccuRevUserForumisavaluableresource.
InadditiontoaccesstoAccuRev'sinternationalusercommunity,theUserForumistheplacetogoforresourceslike:TheAccuRevknowledgebaseTheAccuRevFAQRegisterasaUserForummembertoday.
AccuRevdocumentation--http://www.
accurev.
com/documentation.
htmlThispageprovidesaccesstoAccuRevproductdocumentationforallcurrentandpreviousreleasesofmostAccuRevproducts.
xGitCentricUser'sHelpGitCentricUser'sHelp11.
ConceptsandOverviewThischapterprovidesanintroductiontotheconceptsbehindAccuRevGitCentric.
WhatisAccuRevGitCentricAccuRevGitCentricisabridgebetweentwoworlds:theopensourceGitrevisioncontrolsystemtheEnterprise-capableAccuRevsourcecontrolmanagement(SCM)systemGitispopularwithmanydevelopersforitssimplicityandspeed.
However,professionalenterprisesneedmorecontrolandscalabilityfortheirlargeinvestmentinintellectualproperty.
ManydeveloperspreferAccuRev'sinterface;releaseengineersrequireAccuRev'sstreamarchitectureforcapturingtheexactrevisionsneededforabuildenvironment,andmanagersrequireAccuRev'sTimeSafeauditablilityanditsACL-basedsecurity.
HowdoesanorganizationmeetthesedifferingrequirementsandpreferencesAccuRevGitCentricprovidesenterpriseswiththesolution:developerswhoembraceGitcancontinueusingGitthesamewaytheydotoday,whileotherdevelopmentgroups,releaseandtestengineers,andmanagerswhorequireAccuRev'spower,functionality,andsecuritycanworktogetherviatheAccuRevGitCentricinterface.
GitCentricalsoincorporatestheopensourceGerritCodeReviewpackageforoptionalcodereviewfunctionality.
Inthemostbasicterms,GitrepositorybranchesaremappedtoAccuRevstreams,sothatthetwostayinsync.
ChangestotheGitrepositorygettransmittedtotheAccuRevdepot,andchangesintheAccuRevdepotgettransmittedtotheGitrepository.
Updateshappenautomatically.
GitusersdonotneedchangetheirworkpracticesfortheAccuRevenvironment,sinceGitCentricistransparenttothem.
GitCentricfunctionalityappliestotwoaudiences:Regularuserscanregisterthemselves,maintaintheirpreferences,and(ifimplementedattheirsite)accesstheoptionalcodereviewfunctionality.
Administratorscanconfigureandmaintainrepositories,theirsecurity,andtheirbranchmappingstoAccuRevstreams.
WheretogoforMoreInformationWhenusingGitCentric,thedocumentationyouneeddependsonwhatcomponentyouareusing.
ForGitCentricinstallation,seetheAccuRevGitCentricInstallationandReleaseNotes.
2GitCentricUser'sHelpForGitCentricadministrationanduse,you'realreadyhere:theAccuRevGitCentricUser'sHelp(availableinbothPDFandHTML)fromtheGitCentricwebinterface:ForhelpwithGerritCodeReview,seetheGerritCodeReviewdocumentationhere:http://gerrit-documentation.
googlecode.
com/svn/Documentation/2.
6/index.
htmlForGitdocumentation,youcanusegithelpfromthecommandline.
Youcanalsouseasearchenginetolocateseveralgoodtutorialsanddiscussionsavailableontheweb.
ForAccuRevdocumentation,accessthecompletedocumentationsetinHTMLandPDFfromtheHelpContents&ManualsmenuintheAccuRevJavaGUI:TheAccuRevInstallationandReleaseNotesareavailablefromthedocumentationdownloadpageontheAccuRevwebsite:http://www.
accurev.
com/documentation.
htmlANoteAboutTerminologyBecauseGitCentricspanstheenvironmentsofAccuRev,Git,andGerritCodeReview,youmayencountersomeconflictsoroverlapsinterminology.
Forexample,GerritCodeReviewoftenusestheterm"project"torefertoarepository.
AccuRevusestheterms"repository"or"repo"whenreferringtoarepository,andreservestheterm"project"forreferringtospecificGerritfunctionality,orwhenreferringtosomekindofplannedordefinedundertaking.
SeeAppendixDGitCentricGlossaryfordefinitionsoftermsusedinGitCentric.
GitCentricUser'sHelp3BasicArchitectureThefollowingdiagramshowsthebasicconfigurationofaverysimpleGitCentricenvironmentwheretheGitrepository,Tomcatwebserver,andAccuRevserverwithdatabasesforbothGitCentricandAccuRevresideonthesameserver:Figure1.
BasicArchitectureInthissimpleconfiguration,theGitCentricserverhosts:aTomcatwebserverconfiguredwithtwoGitCentricapps(abridgeandanadministrativeGUI)anAccuRevserverwhichincludesaPostgreSQLdatabase,andwhichfunctionsasboththeGitCentricAccuRevserverandaproductionSCMAccuRevserverwithatrigger(server_master_trigger)tonotifyGitCentricofchangesinAccuRevaGitCentricinstallationdirectory,whichgenerally(butnotnecessarily)containsastorageareaforonemoreGitrepositorieswhichincludetriggers(pre-receiveandupdate)andconfigurationfiles.
(ThetriggersareGithooksthatgetscopiedtoyourGitCentricreposandwhichhelpkeepAccuRevsynchronizedwithyourrepo.
SearchthewebformoreinformationaboutGithooks.
)Inthissimpleenvironment,theAccuRevserverhostsboththeAccuRevdepotcontainingthestreamsthataremappedtobranchesintheGitrepo,alongwiththedatabaseserverforbothGitCentricandAccuRev,andanothertriggerthatkeepsyourreposynchronizedwithAccuRev.
InfacttheTomcatserverisalsoapartoftheAccuRevinstallation,underthe/WebUIdirectory.
Notethatconfigurationscanbemuchmorecomplex,withaGitrepoononemachine,theTomcatserveronanothermachine,theAccuRevGitCentricserveronyetanothermachine,andremoteproductionAccuRevserversonevenmoremachines.
AdditionalGitrepos,hostedeitheronGitCentricserverlocalstorageoronaSAN(StorageAreaNetwork),andmultipleAccuRevserversonremotehosts,canbeaddedtothemix.
Infact,foralargeenvironment,itislikelythattheproductionAccuRevserverswouldbeonremotehosts,andthattheAccuRevserverontheGitCentrichostwouldbeusedstrictlyfortheGitCentricdatabase.
But4GitCentricUser'sHelpforevaluations,orforsmallerinstallations,itisfinefortheGitCentricAccuRevservertofunctionasboththeGitCentricdatabaseserverandtheAccuRevproductionserver.
Forthesakeofthisdiscussion,wewillassumethesimplerconfigurationwheretheGitrepoandtheAccuRevserver(whichincludestheTomcatserver,theGitCentricdatabase,andtheproductionSCMdatabase)allresideonthesamemachine.
Regardlessofthecomplexityoftheinstallation,thebasicGitCentricprocessremainsthesame:GituserspushandpullfilesbetweentheirlocalGitreposandtheGitCentricGitrepo.
AccuRevuserspromoteandupdatefilesbetweentheirworkspacesandtheAccuRevServer.
AndGitCentrickeepsthebranchesintheGitrepossynchronizedwithstreamsintheAccuRevservers.
GitCentricUsersAllGitCentricusers--whethertheyareGitdevelopersorGitCentricadministrators--useGitCentrictoself-registertheiraccountsandtheirSSHpublickeys,andtomaintaintheiraccountpreferences.
Ifcodereviewisconfigured,thenGitdeveloperswillalsoaccessGerritCodeReviewthroughGitCentric.
However,manyGitCentricfeaturesaregearedtowardadministratorssothattheyconfigureAccuRevserversandtheirmappingstoGitrepositorybranches.
GitCentricAdministratorsandMappingBranchestoStreamsAGitCentricadministratorusestheGitCentricGUI(andoptionallytheGitCentricCLIcommands)toconfigurethemappingbetweenGitbranchesandAccuRevstreams.
AGitrepository("repo")isassociatedwithasingleAccuRevserver,andwithanAccuRevusername(the"serviceaccount")forperformingGitCentricadministrativetasks.
Oncethisassociationisdefined,aGitCentricadministratorcanproceedtomapGitrepobranchestoAccuRevstreamsonthatserver.
ThedirectorywithinastreamthatismappedtoaGitbranchiscalledthe"mountpoint".
Afterthemappinghasbeendone,theGitCentricbridgewebappusestriggerstoautomaticallykeeptheGitrepoandtheAccuRevdepotinsync,whiletheGitCentricGUIgivesyoutheabilitytocreaterepos,mapbranchestostreams,setACLs,etc.
NotethatyoucanhavemultipleGitCentricAccuRevuseraccounts:administrativeuserswhointeractivelylogintotheGitCentricGUI(andanyrelatedAccuRevservers),formanualadministrativetasks"serviceaccount"users,accessedinternallybytheGitCentricbridge,forautomaticallysyncingtheGitreposandtheirmappedAccuRevstreamsServiceaccountusersmustbedefined(eitherasanindividualuser,orasagroup)intheAccuRevserveracserver.
cnffile(s),usingtheASSIGN_USER_PRIVILEGEsettinginAccuRev5.
4orlater.
Note:Bestpracticeistoassignthistoagroup,sodifferentmembersofthegroupcanhavedifferentaccessrights.
Forexample,onememberofthegroupmightbefromanoff-shoreorganization,withdifferentaccessrightsthananothermemberofthegroup.
Thesyntaxfortheentryinacserver.
cnfisASSIGN_USER_PRIVILEGE=IfyouspecifymultipleASSIGN_USER_PRIVILEGEsettings,onlythefirstoneishonored.
GitCentricUser'sHelp5BasicRulesRegardlessofhowmanyGitrepositoriesorAccuRevserversyouconfigure,whenyouassociatearepowithaserver,youmapthematthebranchandstreamlevel:aGitbranchismappedtoanAccuRevstream.
YoucanmapmultipleGitbranches(andmultipleGitrepositories)toasingleAccuRevstream.
YoucanmapaGitbranchtoanydirectorywithinanAccuRevstreamYoucannotmapaGitbranchtomultipleAccuRevstreams.
YoucannotmapaGitbranchtotherootstreaminanAccuRevdepot.
(Ifyouneedtodothis,simplycreateanewstreamofftheroot,andthenmaptothat.
)MappedBehaviorIfyoupushafiletotherepositoryanditwouldrequiremergingwiththeversionofthefileonthemappedAccuRevstream,GitCentriccancelsthepushandinformstheuserthatheorshemustpullthelatestchanges,mergeandretrythepush,thesamewayGitalwayshandlesthesesituations.
WhenyoufirstmapaGitbranchtoanAccuRevstream,youcanspecifywhetherthefilesinGitoronAccuRevtakeprecedence.
SinceAccuRevstreamsinheritversionsfromtheirbackingstreams,itisimportanttorememberthatifanyelementispromotedtoabackingstreamaboveastreamthatismappedtoarepo,thatelementwillautomaticallybepushedtotherepofromAccuRev.
BestPracticesWhenPlanningYourInstallationGitCentricreflectstheflexibilityofboththeGitandAccuRevenvironments,anditispossibletoconfigureyourrepositoriesandstreamsincountlessways.
However,AccuRevrecommendskeepingthefollowingthoughtsinmind:Gitrepositoriesaresmaller,coherentgroupsoffunctionality.
Youdonotmergefiles,youmergethewholerepository.
AccuRevdepotstendtobelargesetsoffilesrelatedtoentireproducts,ormultipleproducts.
Therefore,youprobablydonotwanttocreatearepositorythatmapstoanentiredepot.
YouwantyourGitbranchestomaptodirectorieswithinAccuRevstreamsthatcontainsmaller,independentsectionsoffunctionality.
Aswithanynewtool,itisimportantthatyoufirstunderstandwhatyourcurrentprocessis.
IfyouareanexistingGitshop,makesurethatyouhaveaclearpictureofhowyourrepositoriesandbranchesareconfigured,andwhatyourworkflowis.
Inevaluatingthis,youmayfindthatyouneedtobetterdefineyourcurrentenvironment.
Ifyouhavenevergonethroughthisexercise,considersearchingforthefollowingtermsontheweb:"git","workflow",and"model".
ThiswillpointyoutosomegooddiscussionsaboutsuccessfulGitimplementations.
Oncethisisdone,thenyouwillbeinabetterpositiontodecidehowtomapyourbranchestoAccuRevstreams.
Also,rememberthatbothGitandAccuRevbringdifferentstrengthstoyourorganization.
Gitprovidesaconvenient,distributedversioncontrolsystemtoyourdevelopmentendusers.
AccuRevprovidespowerful,centralizedversioncontrolforuserssuchasbuildadministrators,releaseengineers,productmanagers,etc.
Gitbranchescanbesomewhattransient--ifyoustarttodevelopsomethingonabranchandthenchangeyourmind,youcandeletethebranch.
AccuRevisTimeSafe--allversionsandtransactionsarecapturedpermanentlyintheAccuRevdatabase.
Whencarefullyplanned,mappingbetweentheseenvironmentsmeansthatGitCentricprovidesthebestofbothworldstoyourorganization.
6GitCentricUser'sHelpKeepingGitMergesandAccuRevPromotesinSyncWhenyouconfigureaGitrepositorytoworkwithAccuRevthroughGitCentric,youmapaGitbranchtoanAccuRevstream.
IfyouwishtotakeadvantageofAccuRevpromoteoperations,youmaptheparentAccuRevStreamtoonebranch,andthechildAccuRevstreamtoanotherbranch.
Figure2.
GitMergesandAccuRevPromotesIfyouconfigurethingscorrectlyandfollowafewbasicrules,then:MergesbetweenthemappedbranchesinGitwillresultinanAccuRev"promote"betweenthecorrespondingstreams.
PromotesfromthechildstreamtotheparentstreaminAccuRevwillresultinamergebetweenthecorrespondingbranchesintheGitrepositoryifthecontentunderthemountpointisemptyinthechildstream.
(Thatis,themergewillhappenifthechildstreamiscompletelyinheritedsothatitisthesameastheparentatthemountpoint).
Notethatthedesiredconditionwhentheseoperationsarecompletedisforthe"defaultgroup"inAccuRevstream"C"tobeempty.
(The"defaultgroup"isthesetofelementsorfilesinastreamthatareundercurrentdevelopment.
Afileisremovedfromastream'sdefaultgroupwhenthatfileiseitherpromotedor"reverttoback"ed(orpurged).
SeetheAccuRevdocumentationformoredetails.
)Toensurethatthishappensreliablyandpredictably,configureyoursystemsothat:1.
Onestreamistheparentofanotherstream,andeachofthesestreamsaremappedtobranchesintheGitrepository.
Inthisexample,theparentstreamiscalled"P"andthechildstreamiscalled"C"2.
ThereisnotimestamponAccuRevstream"C".
(Atimestampwillpreventastreamdefaultgroupfrombeingcleared.
)3.
ThemountpointmustbethesameineachAccuRevstreamforthebranchesthataremappedtothem.
(Ifonebranchismappedtoonemountpointinonestream,andtheotherbranchismappedtoadifferentmountpointintheotherstream,thefileswillneverlineup.
)GitCentricUser'sHelp74.
AnyAccuRevrulesthatareappliedtotheCstreamarealsoappliedtothePstream.
(Forexample,avoidinclude/excluderulesonestreamthatcausethatcauseitscontentstodifferrelativetotheotherstream.
Anddonotusecross-linksonwritableelements.
)FromaGitviewpoint,thisensuresthatthebranchespointtothesamecommitgraphswhentheircontentsareidentical.
FromanAccuRevviewpoint,thisensuresthatthedefaultgroupsinthestreamsgetclearedoutwhenappropriate,anddonotkeepgrowingtoinclude(potentially)allfilesinthesystem.
BestPracticeforKeepingMergesandPromotesinSyncAccuRevrecommendsthatyoumergeintothechildbranchfirst,andthenfastforwardmergetheparentbranch.
Ifyoumergeintothechildbranchfirst,AccuRevwillreflectthisbyperformingapromotefromthechildstreamtotheparentstream.
However,ifyoumergeintotheparentbranchfirst,AccuRevwillachievethedesired"zerodefaultgroup"statebyperforminganAccurevpurgeonthechildstream.
TheGitcommandsformergingintothechildbranchare:1.
gitcheckoutC2.
gitmergeP3.
gitcheckoutP4.
gitmergeC(Thiswillbeafast-forwardmerge.
Existingmergecommitwillbereused.
)5.
gitpushScenariosforMappingMultipleRepositoriestoaSingleStreamTherearetwocommonreasonsformappingtwodifferentGitrepositoriestothesameAccuRevstream:Project-basedSecurity-basedProject-basedFigure3.
Project-based(samestream,differentmountpoints)8GitCentricUser'sHelpInthiscase,youmighthavetwodifferentpartsofaproductintwodifferentdirectorystructuresinthesamestream,suchasaGUIdevelopmenttreeandadatabasedevelopmenttree.
IntheGitenvironment,youcouldhavetheGUIworkbeingdoneinonerepositoryandthedatabaseworkbeingdoneinanother.
Bymappingthebranchesintheserepositoriestothecorrectmountpointsinthesamestream,youcankeeptheworkseparate.
(Keepingthebranchnamesconsistentacrossreposwillbehelpfulifyouneedtomakebranch-mappingchangesenmasseusingthechildren-ofoptionintheSSHconfig-branchCLIcommand.
)Security-basedFigure4.
Security-based(samestream,samemountpoint,differentserviceaccount)Inthiscase,youcouldhavetwodifferentsetsofuserswithdifferentaccessprivilegesaccessingthesamefiles.
PrivilegedGitdevelopersincorporateheadquarterscouldhaveonerepomappedtothemountpointwithoneserviceaccounthaving"lenient"AccuRevACLs(seebelow).
Lessprivilegedoff-shorecontractdeveloperscouldhaveadifferentrepomappedtothesamemountpointwithadifferentserviceaccounthavingmuchmorerestrictiveAccuRevACLs.
SeeConfiguringforSecurityonpage9formoreinformationaboutACLsandsecurity.
Also,bymappingbranchesfromdifferentrepostoasingleAccuRevstream,youcanautomatetheprocessofupdatingreposwithchanges:whenachangegetspushedtoarepothatismappedtoanAccuRevstream,thatchangegetspropagatedtoallotherbranchesthataremappedtothatstream(assumingthattheAccuRevACLsallowarepoto"see"thechangedfile).
MultipleReposandMultipleServersFigure1aboveillustratesasimplecaseofasingleGitrepositorybeingassociatedwithasingleAccuRevserverthroughGitCentric.
Figure3andFigure4aboveillustratemultiplerepositoriesbeingmappedtoasingleAccuRevserver.
However,GitCentriccanalsoconfiguremultipleGitrepositorieswithmultipleAccuRevservers.
Forexample,youcouldhaveonerepoassociatedwithoneAccuRevserver,andtwootherreposassociatedwithadifferentAccuRevserver.
(However,asinglerepocannotbeassociatedwithmultipleAccuRevservers.
AndhavingmultipleGitCentricserversconfiguredwiththesameAccuRevserverisnotsupported.
)GitCentricUser'sHelp9IfyouchoosetoconfiguremultipleAccuRevservers,AccuRevstronglyrecommendsthatyouusethesameGitCentricadministratoruserandpasswordforallAccuRevserverstoavoidtheneedtoconstantlyloginandoutasyoumovebetweenservers.
Figure5.
MultipleAccuRevServersNotethatifyouchoose,youcanadministeryourGitreposwithGitCentricandnothavetheirbranchesmappedtoanyAccuRevstreamsatall.
YoudoneedtoassociateaGitrepositorywithanAccuRevserverforsecuritypurposes,butyoudonotneedtohaveitsbranchesmappedtouseGitCentric.
AccuRevReplicaServerRestrictionIfyourAccuRevinstallationhasoneormorereplicaservers,youshouldalwaystrytoassociateGitCentricwiththeAccuRevmaster(ifpossible),andNOTareplica.
EvenifyourGitCentricinstallationisphysicallylocatedincloseproximitytoareplicaserver,youshouldtrytoconfigureGitCentrictoworkwiththeremotemasterAccuRevserver,notthegeographicallycloserreplicaserver.
(ThismaynotbepossibleifyourinstallationhasimplementedfirewallsandVPNorsomeotherkindofsecuritythatpreventsyoufromcommunicatingdirectlywitharemotemasterserver.
)ConfiguringforSecurityAstoucheduponinFigure4onpage8,oneoftheadvantagesofusingAccuRevGitCentricinaGitenvironmentisthatyoucanusebothGitCentricandAccuRevsecurityfeaturestocontrolaccesstofiles,afeaturenotnativelyprovidedbyGit.
10GitCentricUser'sHelpGitCentricmakesuseoftwokindsofAccessControlLists("ACLs"):GitCentric"group-based"ACLs,whichdefineaccesstoGitrepositories.
AccuRevElementACLs,whichdefinepermissionsontheAccuRevserverdowntotheindividualelementlevel.
UsingthesetwotypesofACLs,youcanapproachGitCentricsecurityintwoways:UsingGitCentricgroup-basedACLstospecifyallowanddenyprivilegesonarepository("project")basis.
Mappingmultiplereposasdifferent"views"onAccuRev-controlledelements.
TheAccuRev-controlledelementsmayoptionallybesecuredwithAccuRevElementACLs(EACLs).
GitCentricGroup-BasedACLsOntheGitside,youdefinegroup-basedACLsandapplythemtorepositories,tocontrolwhatkindofaccessgroupmembershavetoGitCentric-controlledGitreposandbranches.
(GitCentricgroup-basedACLsaredifferentthan--andshouldnotbeconfusedwith--AccuRevElementACLsor"EACLs",whichcontrolaccesstofilesontheAccuRevserver.
)GitCentricprovidesfivesystemorpre-definedinternalorgroups:Administrators(internal)AnonymousUsers(system)Non-interactiveUsers(internal)Repository("Project")Owners(system)Registeredusers(system)Youcandefinemoregroupsasnecessary.
GitCentricisinstalledwithabasicsetofACLsonaspecial,system-definedprojectnamed"All-Projects",fromwhichallreposinherittheirbasesetofACLs.
ThesebasicACLsaresettobehighlysecure,soyouwillneedtocustomizethemforyoursitebeforeyouruserscanuseGitCentric.
Thegeneraltopicofgroup-basedACLsisbeyondthescopeofthisdocument,soyouwillneedtolearnaboutthemfromtheGerritCodeReviewdocumentationreferencedbelow,butataveryhighlevel:Everyuseraccountisamemberofoneormoregroups,andaccessandprivilegesaregrantedtothosegroups.
Youcannotgrantaccessrightstoindividualusers.
Accessrightsarethenassignedtothesegroupsperrepo(or"project").
Accessrightsgrantedtoparentreposareinheritedbychildrepos.
AccessrightsdefinedfortheAll-Projectsprojectareinheritedbyallotherprojects.
ForinformationaboutcreatingandconfiguringGitCentricgroupACLsfromtheGitCentricUI,seeConfigureAccessRights(ACLs)foraRepoonpage30.
BecauseGitCentricgroupACLsarederivedfromGerritCodeReview,theyaredocumentedindetailintheGerritCodeReviewdocumentation.
SeetheAccessControlstopicintheGerritCodeReviewdocumentationformoreinformation.
ConfiguringMultipleGitReposwithAccuRevandEACLsInAccuRev,itisafairlycommonpracticetoconfiguredepotsandfileswithACLssothatonlycertainuserscanaccessthem.
Forexample,assumethatyouhireanoff-shorecontractcompanytodevelopcodeGitCentricUser'sHelp11foranoptionalfeaturetoyourmainproductline.
Youmightwanttogivestaffincorporateheadquartersaccesstoallfilesanddirectories,whilerestrictingaccessoftheoff-shoreteamtojustthosefilesanddirectoriesthattheyneedtogetthejobdone.
BysettingupACLsintheAccuRevenvironment,andthenmappingGitrepositoriesandbranchestotheseAccuRevdepotsandstreams,youcangivetheoff-shoreteamaccesstojusttherepocontainingtheirfiles,whilegivingyourdomesticteamsaccesstotherepothatcontainsallyourfiles(seeFigure4onpage8).
ForinformationaboutsettingupACLsintheAccuRevenvironment,seethefollowingAccuRevdocumentation:On-LineHelpGuide:Chapter8,"Security"Administrator'sGuide:Chapter9,"AccuRevSecurityOverview"CLIUser'sGuide:eacl,setacl,lsacl,andmkusercommanddescriptionsinChapter2,"AccuRevCommandLineReference"GettingStartedOnceyouhavecompletedthischapter,andafteryouhaveinstalledGitCentricasdescribedintheAccuRevGitCentricInstallationandReleaseNotes,youshouldproceedtoGetStartedonpage13inChapter2Howto.
.
.
tolearnhowtoconfigureyourGitCentricenvironmentanduseitforthefirsttime.
12GitCentricUser'sHelpGitCentricUser'sHelp132.
Howto.
.
.
ThischapterdescribeshowtoperformbasictaskswiththeAccuRevGitCentricGUI.
(ForanexampleofperformingsomeofthesetaskswithCLIcommands,seeCLIExampleonpage85.
)Forproceduresthatapplytoallusers,proceedtothenextsection.
ForproceduresthatapplyonlytoAdministratorusers,seeProceduresforAdministratorsOnlyonpage19.
ProceduresforAllUsersTheprocedureswithinthissectionapplytobothregularusersandadministrators.
GetStartedThissectionassumesthatyouhavecompletedthebasicinstallationstepsdescribedintheAccuRevGitCentricInstallationandReleaseNotes.
NowyouwillperformsomeconfigurationstepsandactuallyusetheGitCentricGUIforthefirsttime.
Note:Note:Administrators--BeforeyoubegintoassociateGitrepositoriesandbrancheswithAccuRevdepotsandstreams,youmusthaveasolidunderstandingofyourcurrentGitandAccuRevprocesses.
PleasebesuretoreadthroughChapter1ConceptsandOverview,particularlyGitCentricAdministratorsandMappingBranchestoStreamsonpage4,MappedBehavioronpage5,andBestPracticesWhenPlanningYourInstallationonpage5.
CreateanSSHkeyThissectionappliestoallGitCentricusers,whetheryouareanadministratororanenduser.
Note:GeneralSSHdocumentationisbeyondthescopeofthisdocument.
Werecommendthatyouuseyourfavoritesearchenginetofindinformationaboutthetopic.
However,GitCentricadministratorsshouldknowthattheGitCentricinstallernowincludesanSSHDdaemon,andtheproductnowTable1.
SummaryofCommonGitCentricProceduresforALLUsersTo:Gotopage:GetStarted13CreateanSSHkey13LogIntoGitCentric14RegisterwithGitCentric15SetPreferences16CreateaCloneFromaGitCentricRepository17SwitchBetweenGerritCodeReviewandGitCentric1914GitCentricUser'sHelpincludesaself-registrationfeature.
ThismeansthatunliketheKando2012.
1release,younolongerneedtomanuallyinstallandconfigureanSSHserver,andyounolongerneedtocreateandregisterSSHkeysforyourusers.
1.
IfyouknowwhatanSSHpublickeyis,andyouknowthatyouhaveone,andyouknowwhereyourpublickeyfileis,youareallset!
Youcanskipaheadtothenextsection.
2.
Ifyouneedtogenerateakey,usethefollowingsyntax:ssh-keygen-trsa-C@Note:Ifyouareanend-useronaWindowsmachine,youshouldinstallaGitWindowsclientsuchasmsysGit,whichincludesssh-keygen.
Seehttp://msysgit.
github.
comformoreinformation.
Makenoteofwhereyourpublickeyisstored.
Typicallyitisin~/.
ssh/id_rsa.
pub(orC:\users\\.
ssh\id_rsa.
pubonWindows).
YouwillneeditwhenyoufirstlogintoGitCentric.
LogIntoGitCentricThefirststepinusingtheGitCentricwebGUIislogginginwithyourwebbrowser.
1.
PointyourbrowsertotheGitCentricwebserver.
Forexample:http://Youwillseethefollowinglog-inscreenandtheGitCentricmenuswillbedisplayed,althoughsomewillbedisableduntilyoulogin.
Note:TheveryfirstusertologintoGitCentric,whoshouldbetheadministratorthatinstalledit,willseeaslightlydifferentlog-inscreen,whichincludesafieldforspecifyinga"CLIPath".
ThisinitialloginscreenandprocedureisdescribedintheGitCentricInstallationandReleaseNotes.
2.
Herearethefieldsthatyoumayencounterwitheitherofthesedialogs.
Mostarerelativelyself-explanatorysolongasyouknowthattheUsernameandPasswordareyourcredentialsontheAccuRevserver.
GitCentricUser'sHelp15AccuRevServer:Fromthepull-downmenu,selectthehostnameoftheAccuRevserverthatyouwishtoassociatewithaGitbranch,andwhereyouhavealoginaccount.
Forexample:acserver2:5050,or:5050orlocalhost:5050.
ThismayormaynotbethesameAccuRevserverwheretheGitCentricdatabaseresides.
Inasimpleconfiguration,thisismaybethesamehostthatyoujustconnectedtowithyourwebbrowser,oritmaybearemoteserver.
Notethatiflocalhostappearsasanoption,itreferstoanAccuRevserveronthehostyouareconnectingto,notyourlocalmachinewhereyoustartedyourbrowser.
UserName:--TheAccuRevuseraccountonthisserverthatyouuse.
Ifyouareanadministrator,thiswouldbetheaccountthatyouuseforGitCentricconfiguration,andmightbeanaccountsuchas"acserver"ifyouhavelegacyAccuRevsystems.
SeetheGitCentricInstallationandReleaseNotesforadiscussionaboutuseraccounts.
Password:--ThepasswordforthespecifiedAccuRevuser.
ClickLoginwhendone.
IfthisisyourfirsttimeloggingintoGitCentric,youwillbetakenthroughtheself-registrationprocessdescribedinthenextsection.
Otherwise,youwillbetakentotheGitCentricUI.
RegisterwithGitCentricWhenyoulogintoGitCentricforthefirsttime,youarepromptedthroughaself-registrationprocess.
ThisisprovidedsothatuserswithvalidAccuRevaccountswillnotneedtoinvolveanadministratoringettingsetuponGitCentric:Enteryourinformationasfollows:1.
FullName:Yourrealname(unlessthisisanaccountforarolesuchas"GuestUser".
16GitCentricUser'sHelp2.
RegisterNewEmail.
.
.
:Youshouldenterthesameemailaddressherethatyouspecifiedwhenyouspecifiedyouruser.
emailconfigurationforyourGitclone(s).
YoucanspecifymultipleemailaddressesandswitchbetweenthemasnecessarywiththePreferredemailsetting.
Note:IfyourAccuRevuseraccountisassociatedwithanemailaddress,thataddresswillbeautomaticallyinsertedinthisfield.
3.
PreferredEmail:EnterthesameemailaddressherethatyouspecifyfortheGituser.
emailconfigurationforyourclones.
Ifthesedonotmatch,pushesfromyourclonewillfail.
Ifyouneedtomaintainmultipleemailaddresses,youcanaddthemlateratMyAccount->ContactInformation.
(SeeContactInformationonpage51.
)4.
SSHkey:ClicktheAddbuttonandcopythecontentsofyourSSHpublickeyfilehere(seeCreateanSSHkeyonpage13)andSaveit.
(Note:IfyourAccuRevuseraccountisassociatedwithanSSHpublickey,thatkeywillbeautomaticallyinsertedinthisfield.
)YourpublicSSHkeyfileistypically~/.
ssh/id_rsa.
pub.
YoucanchoosetodothislaterthroughMyAccount->PublicKeys(seePublicKeysonpage51),butuntilthisisset,youwillonlybeabletousethecodereviewfeaturesofGitCentric.
5.
ClickContinuewhendone.
SetPreferencesGitCentricprovidesadialogforcontrollingvariousaspectsofyourdisplay.
1.
ClickMyAccountintheupper-rightcornerofthewindow.
2.
IntheresultingMyAccountmenu,clickPreferences.
GitCentricUser'sHelp173.
Mostofthesesettingsareself-explanatory,andaresummarizedonthereferencepageatPreferencesonpage50.
However,theShowSiteHeadersettingisnon-obviousandrequiressomeset-uptomakeitwork.
Usethefollowingproceduretosetupasiteheader(andfooter)withinGerritCodeReview.
DefineandDisplayaSiteHeaderorFooterforGerritCodeReviewGerritCodeReviewprovidestheoptionofdisplayingaheaderand/orafooterinitswebUI:1.
Createanimagefileorfilesthatyouwantdisplayedfortheheaderand/orfooter.
Placethefileorfilesin/site/static2.
CreateanXML-compliantfilenamedGerritSiteHeader.
htmlin/site/etc.
Includeapointertotheimagefileorfilesin/site/staticthatyouwanttousefortheheader.
NotethatthisfilemustbevalidXHTML.
ItisnotsufficientforittobevalidHTML.
Forexample,thefollowingexamplewouldnotworkifyouleftoutthesuperfluous""closingtags.
Thisexamplecreatesasiteheaderfromtwoimagefilesdisplayedhorizontallyasatablerow,withalinktotheAccuRevwebsitefromthesplashimage.
Example: