On 06/20, Stefan Beller wrote:
> On Tue, Jun 20, 2017 at 12:19 PM, Brandon Williams <bmwill@xxxxxxxxxx> wrote:
> > Introduce the repository object 'struct repository' which can be used to
> > hold all state pertaining to a git repository.
> >
> > Some of the benefits of object-ifying a repository are:
> >
> > 1. Make the code base more readable and easier to reason about.
> >
> > 2. Allow for working on multiple repositories, specifically
> > submodules, within the same process. Currently the process for
> > working on a submodule involves setting up an argv_array of options
> > for a particular command and then launching a child process to
> > execute the command in the context of the submodule. This is
> > clunky and can require lots of little hacks in order to ensure
> > correctness. Ideally it would be nice to simply pass a repository
> > and an options struct to a command.
> >
> > 3. Eliminating reliance on global state will make it easier to
> > enable the use of threading to improve performance.
> >
> > Signed-off-by: Brandon Williams <bmwill@xxxxxxxxxx>
>
> > +/*
> > + * Initialize 'repo' based on the provided 'gitdir'.
> > + * Return 0 upon success and a non-zero value upon failure.
>
> Non zero or negative? The point of the question is if we want to
> ask users of this function to be cautious early on. So in the future,
> do we want to rather see
>
> if (repo_init(...))
> die("you're doomed");
>
> or rather
>
> int x = repo_init(...);
> if (x < 0)
> die("you're doomed");
> else if (x == 1)
> warning("you're not doomed, but close."\
> "Not distimming the gostaks.")
> else
> ; /* we're fine, carry on with life */
>
> I guess we can still refactor later, it's just one
> thing to thing about when introducing an API
> that will likely be used a lot down the road.
I'm not sure what we want right now, hence why I left it a little more
vague. At this point in time all the relevant callers I can think of
(or rather potential callers) don't care about the failure and just want
to know if it succeeded. I think it would be ok to do a small refactor
at a later time if we really needed to provide the reason for the
failure. Unless of course someone feels strongly enough that it needs
to be addressed right now. If we did address it now then we would need
a group of #define's or maybe an enum to describe the failure modes.
>
> > +struct repository {
> > + /* Environment */
> > + /* Path to the git directory */
> > + char *gitdir;
> > +
> > + /* Path to the common git directory */
> > + char *commondir;
> > +
> > + /* Path to the repository's object store */
> > + char *objectdir;
> > +
> > + /* Path to the repository's graft file */
> > + char *graft_file;
> > +
> > + /* Path to the current worktree's index file */
> > + char *index_file;
> > +
> > + /* Path to the working directory */
> > + char *worktree;
> > +
> > + /* Configurations */
> > + /*
> > + * Bit used during initialization to indicate if repository state (like
> > + * the location of the 'objectdir') should be read from the
> > + * environment. By default this bit will be set at the begining of
> > + * 'repo_init()' so that all repositories will ignore the environment.
> > + * The exception to this is 'the_repository', which doesn't go through
> > + * the normal 'repo_init()' process.
> > + */
> > + unsigned ignore_env:1;
> > +
> > + /* Indicate if a repository has a different 'commondir' from 'gitdir' */
> > + unsigned different_commondir:1;
> > +};
>
> I applaud the effort towards documenting what each variable is
> supposed to contain. But some of them read like
>
> /* increments i by one */
> i++;
>
> which is considered bad comment style (it doesn't add
> more information, it just wastes a line), so specifically for
> all the "Path to X" comments:
> * Are they absolute path, or relative path?
> If relative, then relative to what?
> * Can they be NULL? When?
>
> (* Why do we need so many path?
> Could one of them be constructed using
> another and then hardcoding a string relative to it?
> This question may rather be answered in the commit
> message)
Thanks for pointing this out. I'll work a little bit more on the
comments to be more descriptive. I do think that all field names should
probably be commented though.
--
Brandon Williams
